change
Skill0 starsChanged 28 days agoMITView on GitHub
Run a bounded brownfield change (bugfix, small feature, behavior tweak) against an existing spec or codebase: proposal -> one task bundle -> dev/QA -> converge -> archive. Use when an existing spec or codebase needs an incremental change (bugfix, small feature, behavior tweak) and a full PRD is overkill. Do not use for greenfield requirements (use prd-generator), architecture decisions (use spec-generator), or pure task slicing (use task-decomposition).
10 other projects use a version of this.
Adopted by
Most recently taken up by
- Arasz/ai-badgertheir own version, first seen Nov 16, 2026
- dmitribogatenkov/briefprooftheir own version, first seen Nov 8, 2026
- sanjeevkumarraob/chartertheir own version, first seen Oct 25, 2026
- iadr-dev/greenlighttheir own version, first seen Oct 20, 2026
- RTekaya/app-factorytheir own version, first seen Oct 15, 2026
- luiscortex/superpowers-freeze-specstheir own version, first seen Oct 11, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- microsoft/fluentui★ 20ksame name
- dmitribogatenkov/briefproof★ 68same name
- drafthq/draft★ 40same name
- samson-art/transcriptor-mcp★ 24same name
- Arasz/ai-badger★ 3same name
- iadr-dev/greenlight★ 2same name
- benbatya/claude-skills★ 0same name
- luiscortex/superpowers-freeze-specs★ 0same name
- RTekaya/app-factory★ 0same name
- sanjeevkumarraob/charter★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- changeSkill
- convergeSkill
- devSkill
- diagnose-windows-sandbox-aclSkill
- plan-linterSkill
- prd-generatorSkill
- qaSkill
- quality-engineeringSkill
- reviewSkill
- spec-generatorSkill
- task-decompositionSkill
- test-engineeringSkill
- diagnose-windows-sandbox-aclSkill
- convergeSkill
- devSkill
- plan-linterSkill
- prd-generatorSkill
- qaSkill
- quality-engineeringSkill
- reviewSkill
- spec-generatorSkill
- task-decompositionSkill
- test-engineeringSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. 0 are common, 6 are distinctive, and 10 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Add a bounded, reviewable change to an existing specification and codebase without writing a new PRD.
- Very specific: line 76
Read .specs/change-context/standards.md before planning.
- Very specific: line 101
Keep 02/03 blank role forms.
- Distinctive: line 103
Gate 1, then Gate 2: Run deterministic Gate 1, then independent semantic review:
- Very specific: line 113
Implement and verify: Run dev (only declared touch_files, fill 02, hand off) and qa (independent tests under tests/acceptance/, fill 03, …
- Very specific: line 117
Converge and archive: After QA_PASSED, run converge to append confirmed deviations to .specs/02-tech-spec.md, write convergence.md, move …
- Very specific: line 125
Create tasks/<change-id>/ four-document bundle using task-decomposition templates or the fallback in references/brownfield-protocol.md.
- Distinctive: line 126
Run Gate 1 / Gate 2 checklists manually.
- Distinctive: line 127
Follow workflow steps 5–6 with the same artifacts.
- Very specific: line 146
Never invent file paths: Every touch_files entry must be an existing file to modify or a new file in an existing directory to create …
- Distinctive: line 150
Do not invent commands or conventions: Only commands evidenced by declared configuration (the standards report) may appear in the contract …
- Very specific: line 152
A structural change escalates: If the change needs a new spec section/anchor, a new component, a new ADR, or an invariant change, stop and …
- Very specific: line 166
All helpers are stdlib-only, resolve their own directory, and exit 0 (success), 1 (gate failure), 2 (usage error), 3 (unexpected error).
- Very specific: line 170
Missing base spec: Stop. A brownfield change requires a base spec.
- Very specific: line 171
Unknown anchor: Stop and reuse an existing anchor, or escalate to spec-generator.
- Distinctive: line 174
Scripts unavailable: Follow manual fallback; workflow is prompt-first.
“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Change (Brownfield)
Add a bounded, reviewable change to an existing specification and codebase without writing a new PRD. One change produces one proposal plus exactly one four-document task bundle; after QA passes, the confirmed deltas are written back into the spec and the proposal is archived. This skill is prompt-first: every step has a manual fallback and the bundled scripts are optional helpers.
Pipeline position: spec-generator -> change -> task-decomposition -> plan-linter (Gate 1) -> review (Gate 2) -> dev -> qa -> converge -> archive.
existing spec + bounded change
-> .specs/change-context/standards.md (standards_extract.py; implicit constraints)
-> .specs/changes/<change-id>/proposal.md (lifecycle: proposed -> applied -> archived)
-> tasks/<change-id>/01..04 (one contract, one bundle)
-> Gate 1 plan-linter -> Gate 2 review -> dev <-> qa -> converge -> archived proposalUse when
- An existing spec or shipped codebase needs an incremental change: a bugfix, a small feature, a behavior tweak, a bounded NFR adjustment.
- The change can reuse an existing
#sec-*anchor and fits the micro/standard diff budget. - You want the proposal -> apply -> archive loop while keeping this repository's 4-document task protocol and one-owner-per-file roles.
Do not use when
- The work is greenfield, or no upstream spec exists yet: use
prd-generator, thenspec-generator, thentask-decomposition. - The change needs a new architecture decision, a new component boundary, a new cross-cutting
invariant, or a brand-new spec section (a new
#sec-*anchor): escalate tospec-generatorinstead of smuggling it into a change. - You only need to slice an approved spec into tasks: use
task-decomposition. - You only need to audit existing bundles or proposals: use
plan-linter. - The task is already planned and awaiting implementation/verification: use
dev/qa.
Inputs
- The base specification:
.specs/02-tech-spec.md(and its modular parts) by default. - The requirement for the bounded change, written by the requester in plain language.
- The repository conventions report generated in step 1.
- Optional: the existing task bundle the change continues from, and the relevant ADRs.
Outputs
| Artifact | Owner after scaffolding | Purpose |
.specs/change-context/standards.md | Tooling | Deterministic repository standards and implicit constraints (generated, never hand-edited). |
.specs/changes/<change-id>/proposal.md | Planner | Bounded change proposal: motivation, incremental diff, blast radius, invariants/NFR, rollback, verification. |
.specs/changes/<change-id>/convergence.md | Converge tooling | Written after QA passes; records what was folded back into the spec. |
tasks/<change-id>/01-contract.md ... 04-process.md | Planner / Dev / QA / tooling | Exactly one four-document bundle, reusing the task-decomposition templates. |
The proposal is not a PRD and not a replacement spec. It is a delta that names the existing anchors it changes. Full lifecycle and sizing rules: references/brownfield-protocol.md.
Workflow
Extract repository standards (once per configuration change):
python .agents/skills/change/scripts/standards_extract.py --repo-root . --json python .agents/skills/change/scripts/standards_extract.py --repo-root . --checkRead
.specs/change-context/standards.mdbefore planning. Its "Implicit constraints" section is binding: use only the commands it evidences, respect declared test layout, runtime floors, and existing anchors. Exit code1from--checkmeans the report is stale; regenerate before planning. Never hand-edit the report.Scaffold the proposal and one task bundle (the only step that writes files):
python .agents/skills/change/scripts/scaffold_change.py \ --change-id CHG-001-rate-limit \ --title "Rate limit login attempts" \ --anchor "#sec-auth-tokens" \ --kind modify \ --size-class micro --estimated-lines 40 \ --touch-files "modify:src/auth/rate_limit.py" \ --repo-root .The scaffolder validates anchors against the base spec, computes
base_spec_sha256, and delegates totask-decomposition(scaffold_task.py) or emits a minimal inline bundle if absent. Use--dry-runto preview and--forceto overwrite disposable runs.- Planner fills the proposal and the contract. Replace guides in proposal (
motivation,[CHG-<n>]hunks, paths, invariants/NFR, rollback, verification) and contract placeholders (module,adherence_adrs,dod, edge cases, invariant prose). Do not invent paths or anchors. Keep02/03blank role forms; keep proposalstatus: proposed. Gate 1, then Gate 2. Run deterministic Gate 1, then independent semantic review:
# Run from the repository root. The Gate 1 helper requires the plan-linter skill to be installed. python .agents/skills/plan-linter/scripts/plan_linter.py --tasks-dir ./tasks --repo-root . --spec .specs/02-tech-spec.md --changes-dir .specs/changes python .agents/skills/change/scripts/lint_change.py --change-id CHG-001-rate-limit --repo-root .Gate 1 must pass before implementation; Gate 2 must not report
BLOCKEDorREQUEST CHANGES.- Implement and verify. Run
dev(only declaredtouch_files, fill02, hand off) andqa(independent tests undertests/acceptance/, fill03, one verdict). Proposal moves toappliedonce implementation and verification pass. - Converge and archive. After
QA_PASSED, runconvergeto append confirmed deviations to.specs/02-tech-spec.md, writeconvergence.md, move bundle totasks/archive/, and set proposalstatus: archived. Withoutconverge, perform identical append write-back manually.
Manual fallback (no Python)
- Build standards list by hand: repo-root configs, test/source trees, runtimes,
#sec-*anchors. - Copy
assets/templates/proposal.template.mdto.specs/changes/<change-id>/proposal.md, fill every token ({{...}}), and computebase_spec_sha256. - Create
tasks/<change-id>/four-document bundle usingtask-decompositiontemplates or the fallback in references/brownfield-protocol.md. - Run Gate 1 / Gate 2 checklists manually; record evidence in the bundle.
- Follow workflow steps 5–6 with the same artifacts.
Quality-gate checklist
- Standards report generated and current (
standards_extract.py --checkexits 0). - Proposal frontmatter complete,
status: proposed,kindcorrect,base_spec_sha256current. - Every
[CHG-<n>]block names a real#sec-*anchor that exists in the base spec. - Exactly one task bundle exists;
change_idequals proposal id andorigin_spec_anchoris one of the proposal'simpact_anchors. - Diff budget honored: micro is 1 touch file (default 10-49 lines); standard is 1-3 files (default 50-250 lines). Numbers configurable in plan-linter config.
- Gate 1 passes on the filled contract and proposal is open (
proposed/applied). - Gate 2 review has no blocking findings; reviewer is independent and read-only.
- Dev implemented only
touch_files; QA issued exactly one verdict with evidence. - Converge appended deltas to the spec and the proposal is
archived.
Anti-hallucination rules
- Never invent file paths. Every
touch_filesentry must be an existing file tomodifyor a new file in an existing directory tocreate(repo-relative, forward-slashed). - Every diff hunk names a real anchor. Reuse an existing
#sec-*anchor; the scaffolder and linter reject missing or drifted anchors. - Do not invent commands or conventions. Only commands evidenced by declared configuration (the standards report) may appear in the contract DoD.
- A structural change escalates. If the change needs a new spec section/anchor,
a new component, a new ADR, or an invariant change, stop and use
spec-generator. - Do not overstate the gates. Gate 1 is deterministic bookkeeping, Gate 2 is prompt review; git and CI remain authoritative.
Helper scripts
scripts/standards_extract.py— deterministic standards extractor; writes.specs/change-context/standards.md(--json,--check,--dry-run,--version).scripts/scaffold_change.py— creates proposal and one task bundle (--dry-run,--force,--json,--version).scripts/lint_change.py— proposal/bundle consistency and base-spec drift check (--json,--version).
All helpers are stdlib-only, resolve their own directory, and exit 0 (success), 1 (gate failure), 2 (usage error), 3 (unexpected error).
Failure handling
- Missing base spec: Stop. A brownfield change requires a base spec; scaffold exits
2. - Unknown anchor: Stop and reuse an existing anchor, or escalate to
spec-generator. - Stale report or spec drift (exit
1): Regenerate report, rebase proposal, rerun Gate 1; never hand-editbase_spec_sha256. - Change directory exists: Rerun with
--forceonly if disposable; otherwise edit existing proposal. - Scripts unavailable: Follow manual fallback; workflow is prompt-first.
Honest limits
- The standards report describes declared configuration, not necessarily enforced practice; it is a prompt for the Planner, not proof of compliance.
base_spec_sha256detects any byte change to the base spec; after convergence the archived proposal is exempt from drift checks.- Optional scripts are bypassable; CI plus repository permissions remain authoritative.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

