协作头脑风暴
brainstorming
在实现前澄清需求、探索设计选择,并形成清晰的开发方向。
agentic-readiness-assessment【开发与工程】Evaluates a software repository for readiness to be developed and maintained by AI coding agents, and produces an evidence-based readiness scorecard. Use when the user requests an agentic-readiness assessment, readiness scorecard, AI-readiness audit of a codebase, or recommendations for improving AI-assisted development workflows.
独立 GitHub 快照 · 自动分类 · 以原作者文档为准
Read the version field of the plugin's plugin.json and record it as prompt_version in the report run block, so reports produced by different revisions stay comparable. Write unknown if the manifest cannot be read.
Assess whether an AI coding agent can independently understand this repository, find the correct change points, establish a reproducible environment, validate work, and prepare a change for delivery. Produce an evidence-backed improvement backlog for maintainers.
This is an audit. Do not implement features or refactor production code. Create only one file: reports/agentic-readiness.md, a single document holding both the decision content and the supporting evidence.
The only permitted change to any other tracked file is the single reversible probe edit described in Probe, which you revert before writing the report. Preserve all pre-existing user changes.
The deliverable of this task is that report. Any standing instruction to output only code, or to treat an analysis document as a failed task, applies to feature work and not to this audit.
Read references/agent-execution-contract.md before collecting the baseline. Under the explicit constraints in Run and Scope, record the host's model identity, effective permission profile, command boundary, run stop condition, and context telemetry availability. Write unavailable for any field the host cannot evidence, classify it as an agent-environment limitation, and never invent a tool restriction, model pin, or telemetry control. After roughly five attempts to obtain unavailable evidence, stop and record the limitation.
documented or inferred.git restore, git checkout -- ., git clean, or git reset across the tree. Revert the probe by rewriting the exact path you edited.Not found when evidence is absent. Never infer a capability, and never reinterpret a failure as a pass.Never let your own tooling become the finding. If a command fails because of a flag you chose, a wrapper you lack, a missing timing utility, or a typo, retry it correctly and log only the meaningful attempt. Offline, cached-only, or sandbox-restricted flags are your constraints, not the repository's — a failure they cause is never evidence against the repository.
Classify commands before execution:
sudo, or machine-wide changes. Do not run.Run python3 <skill-directory>/scripts/validate_report.py reports/agentic-readiness.md from the audited repository after the provisional report write; <skill-directory> is the directory containing this SKILL.md, not a path inside the audited repository. This is a local-read command that validates the report contract without changing the repository.
Being documented does not make a command safe. A refused command is not a skipped category: record it, name its class, and score on the safe evidence that remains.
Attempt the repository's frozen or locked installation first, in the ecosystem's own idiom. If it fails because resolution data is missing, incomplete, or incorrect, that is a repository finding — record it, then retry once with the ecosystem's non-frozen install using flags that cannot create or modify resolution files, for example npm install --package-lock=false.
Label that result unfrozen fallback. Evidence obtained after a successful fallback is valid for every downstream area: proving that typecheck, tests, and the build actually pass is more useful than reporting them unproven. The setup area itself scores at most half when the fallback was required. If even the fallback fails, or if the ecosystem offers no non-mutating equivalent, record the blocker and move on.
Keep repository readiness separate from limitations of the audit environment:
Route each fix to one owner:
A missing build tool is never a documentation fix. If make, a container runtime, a package manager, or a browser is absent, the owner is agent-environment; documenting the prerequisite instead is a deferred repair. Missing prerequisite documentation is itself a separate repository defect.
Do not invent an external file path or configuration key. If the exact target cannot be established, name the required artifact generically and mark the target unverified.
Read references/assessment-decision-record.md before baseline collection. Use the audit agent only to interpret repository evidence; use deterministic commands for score arithmetic and scripts/validate_report.py for report validation. The requesting human owns scope constraints and must approve an irreversible operation before it runs; otherwise stop and record the command as refused. Keep the delegation map's Cost / Complexity / Risk discipline in the evidence and report the named detection mechanism for any limitation.
Capture the baseline before anything else: tracked and untracked worktree state, stash list, commit, and branch. A dirty tree or pre-existing untracked directory is the baseline, not an error. Record the platform, explicit constraints, and relevant installed tools.
Classify the repository as an application, service, frontend, library, CLI, infrastructure, documentation, data pipeline, monorepo, or an applicable combination. List all components and workspaces in scope.
Before scoring, name the concrete command filling each role, or N/A with justification.
| Role | Application / service | Library / SDK | Infrastructure | Documentation | Data / model |
|---|---|---|---|---|---|
| Deliverable | Build the app or image | Package or compile | Validate or lint the plan | Render the site | Build the pipeline or compile the schema |
| Primary verification | Unit or component tests | Unit tests, API compatibility | Policy or conformance tests | Link, schema, front-matter checks | Schema validation, golden-record tests |
If a role is N/A, name the nearest executable substitute and say what it does not prove. A repository with no executable verification surface at all cannot be Ready.
Determine the intended route from a clean checkout to a delivered change:
setup -> targeted feedback -> full validation -> review or PR
Inspect:
AGENTS.md, CLAUDE.md, repository-local rules, commands, prompts, and skills;Trace one representative feature from its entry point through business logic, persistence or an external boundary, UI when applicable, and tests. Assess whether a newcomer can discover where a similar change and its tests belong. Do not edit the feature.
For every component, find and safely exercise the applicable surfaces: dependency bootstrap; build, packaging, rendering, or schema validation; static analysis; unit tests; integration or contract tests; runtime, API, CLI, or local-preview validation; browser validation; coverage evidence.
Start services only through a documented local or disposable workflow. If execution is unsafe or blocked, record why and classify the blocker; do not invent a substitute that changes the intended workflow.
Compare documentation, executable scripts, observed behavior, and CI. Look for:
Report strengths as well as gaps. Explicitly distinguish an enforced control from a documented intention.
There is no fixed command budget, but an unanswered question is cheaper than an endless search. After roughly five attempts to resolve the same question, stop and record it as not determined, then score the affected area on the evidence you have. Never restart a completed phase.
The command inventory proves only that commands exit 0. The probe proves the repository can guide a change to a verified fix. It is conditional.
Run the probe when the Gate 3 verification command executed in this environment — pass or fail — and the repository has code covered by it.
Record locatability (did the failure name file and line — quote it), loop cost (commands and wall-clock from edit to trustworthy green), signal quality (legible alone, or needed a debugger or outside knowledge), and blockers (what made a one-line change expensive).
Do not run the probe when the Gate 3 surface is repository-blocked or environment-blocked. Record Probe: not attempted with the blocking Fix Record IDs. Do not substitute an unrelated surface: proving that a documentation-mirror or metadata check detects drift says nothing about whether application changes are verifiable, and a substitute never satisfies Gate 4. If you run one anyway, label it non-representative and state plainly what it does not prove.
Score these areas across the full applicable scope. Max is the area's weight.
| # | Area | Max | Gate |
|---|---|---|---|
| 1 | Agent guidance and navigation | 10 | |
| 2 | Reproducible environment and dependency setup | 10 | Gate 1 |
| 3 | Build, package, render, or deliverable validation | 10 | Gate 2 |
| 4 | Lint, format check, typecheck, static analysis, or policy validation | 10 | |
| 5 | Unit or component tests | 10 | |
| 6 | Integration, contract, or functional tests | 5 | |
| 7 | Runtime, API, CLI, or local-preview validation | 5 | |
| 8 | Browser or UI validation | 5 | |
| 9 | Coverage and feedback-loop quality | 5 | |
| 10 | CI enforcement and parity with local validation | 10 | |
| 11 | Safety, test isolation, artifacts, and cleanup | 5 | |
| 12 | Delivery workflow from task through review or PR | 5 | |
| 13 | Agent guardrails and permission scoping | 10 | |
| 14 | Context economy | 5 |
Applicable maximum is 105 when every area applies.
Readiness status and points:
Verification state: Executed, Executed (unfrozen fallback), CI-proven, Environment-blocked, Not run: unsafe, or Not applicable.
An environment blocker is a confidence limitation, not an automatic zero, and never full credit: award at most half the area points, and only when repository evidence is coherent. Score the property, not a named command — there is no universal setup command. Award area 2 for pinned resolution in the ecosystem's own idiom, declared toolchain versions, documented external prerequisites, and an executed clean-checkout path; state whether setup was tested clean or only in a warmed workspace.
Score by capability rather than status. These are not interchangeable: instrumentation that reports an unsafe action afterward is not a control that prevents it. Named mechanisms are examples; credit any runtime's equivalent, including mechanisms outside the agent runtime.
| Capability | Pts | Earns credit |
|---|---|---|
| Prevention | 4 | Blocks an unsafe action before it happens: a pre-tool gate denying reads or writes to secret paths, a scoped allow-list, protected paths, approval before an outward-facing write. |
| Observation | 2 | Records what the agent did: post-edit hooks, audit logs, artifact capture, secret redaction. |
| Completion | 2 | A tracked run-finished signal, so lifecycle state cannot go stale. |
| Enforcement | 2 | Controls outside the agent's cooperation: CI that actually runs the verification suite, pre-commit with a deterministic install path, a non-privileged runtime user, resource limits, restricted egress, branch protection. |
Negative controls cap area 13 at 2 regardless of what else exists, and each is its own P0 or P1 fix record: a permission bypass in any committed script, task runner, container definition, or CI job; a blanket allow-all policy; a readable secret file with no guard; a plaintext credential in the repository or shipped configuration. Report the path, never the value.
A rule that lives only in prose is described, not enforced; it scores under area 1.
Score the cost of reading this repository well enough to change it: oversized files on the paths an agent must actually open, duplicated or contradictory instruction sources, stale instructions that contradict the code, and undocumented generated files an agent may waste effort editing.
Measure, but tie every measurement to observed friction. Counting files over roughly 800 lines is evidence only when one of them sits on the change path you traced, or on the path a Fix Record requires editing. Exclude vendored, generated, and resolution files. A raw size statistic with no friction attached is not a finding.
Each gate is anchored to a scored area. A gate's result is its anchor area's score; never report a separate gate number.
| Gate | Anchor |
|---|---|
| Gate 1 — setup | Area 2 |
| Gate 2 — deliverable | Area 3 |
| Gate 3 — primary verification | The area holding the archetype's primary verification surface, named explicitly: usually area 5, area 6 where functional tests are the real coverage, or area 4 for documentation and infrastructure archetypes |
| Gate 4 — probe | The probe result, or not attempted with its blocking Fix Record IDs |
Gates 1 to 3 pass only when the anchor area is Verified at full points. State which area anchors Gate 3 and why.
Gate 4 passes when the probe's verification detected the defect and the loop returned to green. It fails when the probe ran and nothing detected the defect. When Gate 3 was blocked, Gate 4 is not attempted: it neither passes nor fails, and it caps confidence rather than forcing a status.
normalized score = round(points earned / applicable maximum * 100)
Report the raw total, the applicable maximum, every N/A subtraction, and the addends on one line so a reviewer can re-add them without re-reading the repository.
Verification confidence:
Overall status:
Never let a high average hide a failed gate. Treat the score as a comparison and trend signal; use evidence, gates, and fixes for decisions.
Create one stable record per problem: F-01, F-02, and so on. Findings and actions are one object, so they cannot drift apart. Include:
path:line, executed command with its result, or quoted failure. For a non-repo owner, cite the command you ran in this environment and what it returned.repo, agent-environment, platform, or external-service. Choose the narrowest that actually fixes it.needs-investigation.code, control, docs, or instructions.Priorities:
Every failed gate and every negative control has a record. Prefer code, then an executable control, before docs or instructions. Documentation is not a sufficient fix for a broken command or missing enforcement.
Order records by priority, then by expected effort when reasonably known, so the cheapest high-priority wins come first. Keep environment and platform fixes separate from the repository improvement backlog.
See F-01 in a cell whose purpose is to tell someone what to do.path:line.not measured repeatedly. Include duration only when measured.\|.Write reports/agentic-readiness.md with an # Agentic Readiness — <repository> title, then these thirteen ## sections in this order. Sections 1 to 8 are the decision document, ordered so a reader gets the whole readiness picture before the action list: verdict, then scope, then the scorecard, then what it means and what to do about it. Sections 9 to 13 are the supporting evidence.
One short paragraph: the score, overall status, confidence, a one-sentence readiness conclusion, and the most expensive repository blocker named by ID. No commit, no prompt version, no table.
A single fenced yaml block with exactly these top-level keys, in this order: audited_by, prompt_version, started, completed, commit, branch, platform, archetype, scope, baseline_worktree, final_worktree, clean_state_setup (verified, unfrozen fallback, warmed-workspace-only, or blocked with reason), normalized_score, raw_total, applicable_maximum, status, confidence, and a gates map. Follow references/report-contract.md for the machine-checked values and gate shape.
Then list components, workspaces, and explicit constraints, including the five host-execution fields from references/agent-execution-contract.md or unavailable with their agent-environment limitation.
Reproduce the table below verbatim. It is fixed boilerplate: do not add terms, reword definitions, or expand it with repository-specific detail. Immediately below the table, add exactly one sentence in this format: Gate 3 anchor: Area <4, 5, or 6> — <why this is the primary verification surface>. Add no other content to this section.
| Term | Meaning |
|---|---|
| Area | One of 14 scored readiness dimensions. Each has a weight shown as Max. |
| Gate | One of 4 mandatory checks. A gate's result is its anchor area's score, not a separate number. Gates 1–3 pass only at full points. |
| Probe | Gate 4. A deliberate small defect introduced and reverted, to test whether the repository's own verification catches a real break. |
F-nn | A Fix Record: one stable ID per problem, holding the finding and its fix together. |
| Priority | P0 stops unattended work and needs a human. P1 lets the agent proceed incorrectly or unvalidated. P2 costs avoidable time or clarity. |
| Owner | Who fixes it: repo, agent-environment (the agent's image or toolchain), platform (org or infra config), or external-service. |
| Readiness status | Per area: Verified (full points), Partial (half, rounded down), Repository-blocked (0), or N/A (excluded from the maximum). |
| Verification state | How the evidence was obtained: Executed, Executed (unfrozen fallback), CI-proven, Environment-blocked, Not run: unsafe, or Not applicable. |
| Level | What a fix changes: code, control, docs, or instructions. |
| Normalized score | points earned / applicable maximum * 100. The applicable maximum is 105 minus the weight of every N/A area, so it is rarely 100. |
| Repository blocker | The repository itself is missing, wrong, unsafe, or contradictory. Counts against readiness. |
| Environment blocker | The repository documents enough, but this audit machine lacked a tool, service, or permission. Caps confidence; never a full zero. |
| Enforced control | Something that actually fails when violated. A rule that lives only in prose is documented guidance, not an enforced control. |
| Negative control | A safety defect such as a permission bypass, allow-all policy, unguarded secret file, or committed plaintext credential. Caps area 13 at 2. |
| Unfrozen fallback | The locked install failed, so a non-mutating unlocked install was used instead. Valid evidence, but caps the setup area at half. |
Use:
Area | Applicability | Status | Score | Verification | Evidence / Result | Fix IDs
Include all fourteen areas, then the area 13 capability breakdown and any negative controls found. Follow references/report-contract.md for the machine-checked score and negative-control notation. Close with the raw total, applicable maximum, every N/A subtraction, the addends on one line, and the normalized score. Gate results belong in the next section; confidence belongs in sections 1 and 13.
The Fix IDs column lists IDs only. Do not restate problems here.
Show each gate, its anchor area, its score, verification state, and blocking Fix Record IDs. Include the probe result or the reason it was not attempted.
Open with a compact index table, repository-owned fixes first, then environment or platform fixes:
ID | Priority / Owner | Problem and blocked capability | Fix and target | Verify
Every cell must be actionable on its own. Follow references/report-contract.md for the compact index. Each F-nn ID appears exactly once in the index and has exactly one matching record. Then give the authoritative full record for every F-nn ID, in ID order, with all nine fields. Start each record with ### F-nn, then put each field on its own line as **Problem:**, **Blocks:**, **Evidence:**, **Priority:**, **Owner:**, **Target:**, **Fix:**, **Verify:**, and **Level:**. The index exists for triage and the records exist for execution; keep both, and keep their wording consistent.
Rate the work an AI coding agent can independently undertake today — research, implementation, testing, deliverable validation, runtime or API validation, browser validation, and autonomous task-to-PR delivery — as Yes, Partially, No, or N/A, each with the gate or Fix Record IDs behind it. Rate autonomous delivery Yes only when every gate passes, the probe succeeded, and area 13 scored prevention points above zero.
Give three to five evidence-backed strengths. Mark each as an enforced control or documented guidance, so nobody removes something load-bearing. If there are none, write No strengths identified. and say why.
Resolve each role and gate to an exact command with Role | Resolved command | Source | Status | Justification, including substitutes attempted and what they do not prove. The scorecard and gates cite these commands, so every command named in a scorecard cell must appear here.
Describe the clean-checkout workflow from setup through review or PR, and include the representative feature trace.
What was broken and where, how it was detected, locatability, loop cost, signal quality, blockers, and the baseline comparison result. If the probe was not attempted, state the blocking IDs and stop. If a non-representative substitute was used, say what it does not prove.
List only meaningful commands actually executed, plus commands refused as unsafe with their class:
Command | Directory | Source / Safety Class | Purpose | Result | Notes / Artifacts
Add a duration column only when durations were measured consistently. Exclude attempts that failed because of your own tooling.
Explain the confidence rating, important environment blockers, and any unaudited scope in no more than three short paragraphs. Then list every command or scope that could not be verified, its safety or blocker classification, and which conclusion it leaves uncertain. Nothing else.
Re-read the report and verify:
Verify is runnable or objectively observable;python3 <skill-directory>/scripts/validate_report.py reports/agentic-readiness.md exits 0;agent-environment limitation.Finalization exception: write the provisional report, run the validator, and make one corrective rewrite only if it fails. Run the validator once more after that correction. Then make one finalization rewrite that changes only Commands Executed and Confidence and Limits to record the last validator command and result. The finalization rewrite is permitted even when the provisional report passed; no other rewrite is allowed. Record unresolved validator errors in Confidence and Limits; say that you rewrote it, then stop.
Then respond with the report path, score, overall status, confidence, failed gates, the probe result, and the first repository-owned fix.