@next-friday/create-app 8.0.1 → 9.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/base/.agents/skills/sdlc/SKILL.md +10 -8
- package/templates/base/.agents/skills/sdlc/playbooks/build.md +40 -0
- package/templates/base/.agents/skills/sdlc/playbooks/design.md +1 -1
- package/templates/base/.agents/skills/sdlc/playbooks/open-pr.md +15 -0
- package/templates/base/.agents/skills/sdlc/playbooks/review.md +10 -0
- package/templates/base/.claude/skills/sdlc/SKILL.md +10 -8
- package/templates/base/.claude/skills/sdlc/playbooks/build.md +40 -0
- package/templates/base/.claude/skills/sdlc/playbooks/design.md +1 -1
- package/templates/base/.claude/skills/sdlc/playbooks/open-pr.md +15 -0
- package/templates/base/.claude/skills/sdlc/playbooks/review.md +10 -0
- package/templates/base/.cursor/skills/sdlc/SKILL.md +10 -8
- package/templates/base/.cursor/skills/sdlc/playbooks/build.md +40 -0
- package/templates/base/.cursor/skills/sdlc/playbooks/design.md +1 -1
- package/templates/base/.cursor/skills/sdlc/playbooks/open-pr.md +15 -0
- package/templates/base/.cursor/skills/sdlc/playbooks/review.md +10 -0
- package/templates/base/SETUP.md +1 -1
- package/templates/base/intent/README.md +1 -1
- package/templates/nestjs/AGENTS.md +1 -1
- package/templates/nextjs/AGENTS.md +1 -1
- package/templates/nodejs/AGENTS.md +1 -1
- package/templates/payload/AGENTS.md +1 -1
- package/templates/turborepo/AGENTS.md +1 -1
- package/templates/base/.agents/skills/babysit-pr/SKILL.md +0 -8
- package/templates/base/.claude/skills/babysit-pr/SKILL.md +0 -8
- package/templates/base/.cursor/skills/babysit-pr/SKILL.md +0 -8
package/package.json
CHANGED
|
@@ -10,16 +10,18 @@ Do these steps in order.
|
|
|
10
10
|
|
|
11
11
|
1. **Match the request** to the first row that fits, and read that row's file before you act.
|
|
12
12
|
|
|
13
|
-
| The request | What to do
|
|
14
|
-
| :------------------------------------------------------------------------------- |
|
|
15
|
-
| A question, or a request to explain or check without changing things | Follow [`playbooks/question.md`](playbooks/question.md).
|
|
16
|
-
| An idea, a problem, a ticket, or an incident, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md).
|
|
17
|
-
| A spec for an intent
|
|
18
|
-
| A
|
|
13
|
+
| The request | What to do |
|
|
14
|
+
| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| A question, or a request to explain or check without changing things | Follow [`playbooks/question.md`](playbooks/question.md). |
|
|
16
|
+
| An idea, a problem, a ticket, or an incident, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md). |
|
|
17
|
+
| A spec for an intent, or a path to an `intent.md` | Follow [`playbooks/design.md`](playbooks/design.md). |
|
|
18
|
+
| A build for a spec, a path to a `spec.md`, or a plan the engineer accepted | Follow [`playbooks/build.md`](playbooks/build.md). |
|
|
19
|
+
| A review of a pull request, or a pull request to drive to green | Follow [`playbooks/review.md`](playbooks/review.md). |
|
|
20
|
+
| A later step: a deploy or an incident fix | Say "This step has no playbook in `/sdlc` yet" and name the step. Answer what you can as `playbooks/question.md` says, and stop. |
|
|
19
21
|
|
|
20
22
|
When a request both asks a question and reports a problem, use `question` and offer `plan` in one line.
|
|
21
23
|
|
|
22
|
-
2. **Do the playbook's steps yourself.** Find facts in files and commands instead of asking. Stop only where the playbook says to stop; at a step marked **Gate**, which waits for the person it names and is never skipped; before an irreversible action; or for a decision no file settles. `.agents/rules/agent-owned-work.md` lists the gates and the irreversible actions.
|
|
24
|
+
2. **Do the playbook's steps yourself.** Find facts in files and commands instead of asking. Stop only where the playbook says to stop; at a step marked **Gate**, which waits for the person it names and is never skipped; before an irreversible action; or for a decision no file settles. `.agents/rules/agent-owned-work.md` lists the gates and the irreversible actions. When a playbook's **Next** line says an agent runs the next file in the same turn, read that file and continue without asking.
|
|
23
25
|
3. **Write the reply in the shape below,** following the **Write replies a person can check** convention in `AGENTS.md`.
|
|
24
26
|
|
|
25
27
|
## Reply shape
|
|
@@ -39,7 +41,7 @@ Write every part in the language of the person's message; keep paths, commands,
|
|
|
39
41
|
**Status:** <what is done, what comes next, and which gate it waits on and for whom.>
|
|
40
42
|
```
|
|
41
43
|
|
|
42
|
-
A step that is not finished is `open`, including one that waits at its Gate. Use `skip` only for a step you decide never to do.
|
|
44
|
+
A step that is not finished is `open`, including one that waits at its Gate. When one turn runs more than one playbook, list the steps of each under the playbook's file name. Use `skip` only for a step you decide never to do.
|
|
43
45
|
|
|
44
46
|
When the evidence shows that the change cannot be made in this project, say so under **Request**. In the `plan` playbook, the first round then asks the one question that settles where the change belongs.
|
|
45
47
|
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Build phase: plan, then implement
|
|
2
|
+
|
|
3
|
+
This playbook turns a merged spec into a plan the engineer accepts, and then into working code.
|
|
4
|
+
|
|
5
|
+
1. Find the change: the `intent/<change>/` folder whose `spec.md` or `plan.md` the request names. Its `spec.md` must be on the default branch beside its `intent.md`. In each case below, say only that, in two or three lines, and stop: write no file.
|
|
6
|
+
- The request names no change, or the folder has no `spec.md` on any branch: list each `intent/*/` on the default branch that has a `spec.md` and no `plan.md`, or say that there is none.
|
|
7
|
+
- The spec exists only on another branch: say that the spec is not merged yet, and name that branch.
|
|
8
|
+
- `intent/<change>/plan.md` is already on the default branch: say that the change is built, and name the file.
|
|
9
|
+
2. When `intent/<change>/plan.md` exists on a branch that is not merged, check out that branch. When the request says the plan is accepted, go to step 7. Otherwise show that plan and go to step 5.
|
|
10
|
+
3. Read `intent.md`, `spec.md`, and the code the change touches.
|
|
11
|
+
4. Write the plan from the template below, in the language of the files already in `intent/`. Use exactly the template's headings. An engineer who has never seen this conversation must be able to implement the change from the plan alone.
|
|
12
|
+
- **Files that change:** every file, marked new, changed, or deleted, with one line on what it does afterwards.
|
|
13
|
+
- **Order of work:** numbered steps; each ends with the check that proves it.
|
|
14
|
+
- **Risks:** what the change could break, which step is the riskiest, and each option you chose not to take and why.
|
|
15
|
+
- **Proof:** the tests and commands that show every requirement of the spec is met, by requirement number.
|
|
16
|
+
|
|
17
|
+
Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file: show the plan as the plan.
|
|
18
|
+
|
|
19
|
+
5. **Gate: the engineer accepts the plan.** Ask whether an engineer could build from it, and revise until they say yes. Change no code and commit nothing before that yes. In plan mode, the engineer approving the plan is that yes. When the spec or `AGENTS.md` classes the change as higher risk, say that a tech lead or an architect accepts the plan with the engineer.
|
|
20
|
+
6. Create the branch as `AGENTS.md` says, and commit `intent/<change>/plan.md` as its first commit.
|
|
21
|
+
7. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, first write the test that reproduces the bug, run it, check that it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, make the test pass without editing it, and delete `.git/bug-fix-in-progress`. When the work departs from the plan, change `plan.md` in the same commit.
|
|
22
|
+
8. Run every check under **Verifying your work** in `AGENTS.md` and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent when the project has one, and fix what it reports. When a check cannot run in this session, say which one and why, and never report it as passed.
|
|
23
|
+
|
|
24
|
+
**Next:** `.agents/skills/sdlc/playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
|
|
25
|
+
|
|
26
|
+
## Template
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
# Plan: <title>
|
|
30
|
+
|
|
31
|
+
From `intent/<change>/spec.md`.
|
|
32
|
+
|
|
33
|
+
## Files that change
|
|
34
|
+
|
|
35
|
+
## Order of work
|
|
36
|
+
|
|
37
|
+
## Risks
|
|
38
|
+
|
|
39
|
+
## Proof
|
|
40
|
+
```
|
|
@@ -16,7 +16,7 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
16
16
|
4. Commit `spec.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests. Put the areas of concern first in the pull request's description, under the template's first heading. When you cannot open a pull request from this session, say so and give the pushed branch's name.
|
|
17
17
|
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, accepts the spec by setting `Status: accepted.` and merging the pull request, or rejects it by closing it; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
|
|
18
18
|
|
|
19
|
-
**Next:**
|
|
19
|
+
**Next:** `.agents/skills/sdlc/playbooks/build.md`; an engineer with an agent; when the product owner has merged the spec's pull request and the engineer sends `/sdlc build` with the spec's path.
|
|
20
20
|
|
|
21
21
|
## Template
|
|
22
22
|
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Open the pull request
|
|
2
|
+
|
|
3
|
+
The `build` playbook ends here. Nothing in it stops for a person.
|
|
4
|
+
|
|
5
|
+
1. Clean the diff against the default branch. Remove debug output, commented-out code, changes the plan does not name, and comments that `.agents/rules/code-comments.md` does not allow.
|
|
6
|
+
2. Do what `AGENTS.md` and `CONTRIBUTING.md` require of every change, such as a release note.
|
|
7
|
+
3. When step 1 or 2 changed a file, run the checks under **Verifying your work** in `AGENTS.md` again. When one fails, fix the code and run it again. Commit only when they pass.
|
|
8
|
+
4. Push the branch and open the pull request ready for review, as `AGENTS.md` says for branches and pull requests. When the branch already has a pull request, update that one. Fill the body from `.github/pull_request_template.md`:
|
|
9
|
+
- what changed and why, with the paths of `intent/<change>/spec.md` and `plan.md`;
|
|
10
|
+
- `Closes #<issue>` for each issue the change closes, or the word the template asks for when there is none;
|
|
11
|
+
- each check you ran, with its result copied from the output.
|
|
12
|
+
|
|
13
|
+
When you cannot open a pull request from this session, say so and give the pushed branch's name. When you cannot push either, say so; the review then reads the local branch's diff.
|
|
14
|
+
|
|
15
|
+
**Next:** `.agents/skills/sdlc/playbooks/review.md`; an agent; in the same turn, as soon as step 4 is done.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Review phase: review the pull request and drive it to green
|
|
2
|
+
|
|
3
|
+
1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
|
|
4
|
+
2. Review with a fresh context. Start a subagent that has not seen the work, and give it only the diff, `REVIEW.md`, and the change's `intent/<change>/spec.md` and `plan.md`. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. When the project has no `REVIEW.md`, run three passes: bugs, security, and whether the change matches its spec and plan. A change with no `spec.md` or no `plan.md` is itself a finding.
|
|
5
|
+
3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge.
|
|
6
|
+
4. On a pull request or a branch that this session did not create, skip steps 4 and 5: change nothing and push nothing. Otherwise, fix every Important finding and every Nit that is correct, run the checks under **Verifying your work** in `AGENTS.md`, and push. Answer each finding you do not fix with the reason.
|
|
7
|
+
5. Sweep the pull request: read every unresolved review comment and every failing check, fix what each one reports, push, and answer the comment. Repeat until every check passes and no comment is unanswered. Never skip, disable, or weaken a test to pass a check. When a review flags the same mistake a second time, add the correction to `AGENTS.md` under **Things Claude gets wrong** in the same push. When a check fails for a cause outside this change, such as an outage, say which check and why in one comment, and go to step 6.
|
|
8
|
+
6. **Gate: a code owner approves the pull request, and a person merges it.** You never approve it and never merge it. Report the pull request's URL, or the branch's name when there is none, and that it waits only on the code owner. When a new comment or a failing check arrives, go back to step 5.
|
|
9
|
+
|
|
10
|
+
**Next:** none; the project's deploy workflow; when the pull request is merged.
|
|
@@ -10,16 +10,18 @@ Do these steps in order.
|
|
|
10
10
|
|
|
11
11
|
1. **Match the request** to the first row that fits, and read that row's file before you act.
|
|
12
12
|
|
|
13
|
-
| The request | What to do
|
|
14
|
-
| :------------------------------------------------------------------------------- |
|
|
15
|
-
| A question, or a request to explain or check without changing things | Follow [`playbooks/question.md`](playbooks/question.md).
|
|
16
|
-
| An idea, a problem, a ticket, or an incident, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md).
|
|
17
|
-
| A spec for an intent
|
|
18
|
-
| A
|
|
13
|
+
| The request | What to do |
|
|
14
|
+
| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| A question, or a request to explain or check without changing things | Follow [`playbooks/question.md`](playbooks/question.md). |
|
|
16
|
+
| An idea, a problem, a ticket, or an incident, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md). |
|
|
17
|
+
| A spec for an intent, or a path to an `intent.md` | Follow [`playbooks/design.md`](playbooks/design.md). |
|
|
18
|
+
| A build for a spec, a path to a `spec.md`, or a plan the engineer accepted | Follow [`playbooks/build.md`](playbooks/build.md). |
|
|
19
|
+
| A review of a pull request, or a pull request to drive to green | Follow [`playbooks/review.md`](playbooks/review.md). |
|
|
20
|
+
| A later step: a deploy or an incident fix | Say "This step has no playbook in `/sdlc` yet" and name the step. Answer what you can as `playbooks/question.md` says, and stop. |
|
|
19
21
|
|
|
20
22
|
When a request both asks a question and reports a problem, use `question` and offer `plan` in one line.
|
|
21
23
|
|
|
22
|
-
2. **Do the playbook's steps yourself.** Find facts in files and commands instead of asking. Stop only where the playbook says to stop; at a step marked **Gate**, which waits for the person it names and is never skipped; before an irreversible action; or for a decision no file settles. `.agents/rules/agent-owned-work.md` lists the gates and the irreversible actions.
|
|
24
|
+
2. **Do the playbook's steps yourself.** Find facts in files and commands instead of asking. Stop only where the playbook says to stop; at a step marked **Gate**, which waits for the person it names and is never skipped; before an irreversible action; or for a decision no file settles. `.agents/rules/agent-owned-work.md` lists the gates and the irreversible actions. When a playbook's **Next** line says an agent runs the next file in the same turn, read that file and continue without asking.
|
|
23
25
|
3. **Write the reply in the shape below,** following the **Write replies a person can check** convention in `AGENTS.md`.
|
|
24
26
|
|
|
25
27
|
## Reply shape
|
|
@@ -39,7 +41,7 @@ Write every part in the language of the person's message; keep paths, commands,
|
|
|
39
41
|
**Status:** <what is done, what comes next, and which gate it waits on and for whom.>
|
|
40
42
|
```
|
|
41
43
|
|
|
42
|
-
A step that is not finished is `open`, including one that waits at its Gate. Use `skip` only for a step you decide never to do.
|
|
44
|
+
A step that is not finished is `open`, including one that waits at its Gate. When one turn runs more than one playbook, list the steps of each under the playbook's file name. Use `skip` only for a step you decide never to do.
|
|
43
45
|
|
|
44
46
|
When the evidence shows that the change cannot be made in this project, say so under **Request**. In the `plan` playbook, the first round then asks the one question that settles where the change belongs.
|
|
45
47
|
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Build phase: plan, then implement
|
|
2
|
+
|
|
3
|
+
This playbook turns a merged spec into a plan the engineer accepts, and then into working code.
|
|
4
|
+
|
|
5
|
+
1. Find the change: the `intent/<change>/` folder whose `spec.md` or `plan.md` the request names. Its `spec.md` must be on the default branch beside its `intent.md`. In each case below, say only that, in two or three lines, and stop: write no file.
|
|
6
|
+
- The request names no change, or the folder has no `spec.md` on any branch: list each `intent/*/` on the default branch that has a `spec.md` and no `plan.md`, or say that there is none.
|
|
7
|
+
- The spec exists only on another branch: say that the spec is not merged yet, and name that branch.
|
|
8
|
+
- `intent/<change>/plan.md` is already on the default branch: say that the change is built, and name the file.
|
|
9
|
+
2. When `intent/<change>/plan.md` exists on a branch that is not merged, check out that branch. When the request says the plan is accepted, go to step 7. Otherwise show that plan and go to step 5.
|
|
10
|
+
3. Read `intent.md`, `spec.md`, and the code the change touches.
|
|
11
|
+
4. Write the plan from the template below, in the language of the files already in `intent/`. Use exactly the template's headings. An engineer who has never seen this conversation must be able to implement the change from the plan alone.
|
|
12
|
+
- **Files that change:** every file, marked new, changed, or deleted, with one line on what it does afterwards.
|
|
13
|
+
- **Order of work:** numbered steps; each ends with the check that proves it.
|
|
14
|
+
- **Risks:** what the change could break, which step is the riskiest, and each option you chose not to take and why.
|
|
15
|
+
- **Proof:** the tests and commands that show every requirement of the spec is met, by requirement number.
|
|
16
|
+
|
|
17
|
+
Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file: show the plan as the plan.
|
|
18
|
+
|
|
19
|
+
5. **Gate: the engineer accepts the plan.** Ask whether an engineer could build from it, and revise until they say yes. Change no code and commit nothing before that yes. In plan mode, the engineer approving the plan is that yes. When the spec or `AGENTS.md` classes the change as higher risk, say that a tech lead or an architect accepts the plan with the engineer.
|
|
20
|
+
6. Create the branch as `AGENTS.md` says, and commit `intent/<change>/plan.md` as its first commit.
|
|
21
|
+
7. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, first write the test that reproduces the bug, run it, check that it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, make the test pass without editing it, and delete `.git/bug-fix-in-progress`. When the work departs from the plan, change `plan.md` in the same commit.
|
|
22
|
+
8. Run every check under **Verifying your work** in `AGENTS.md` and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent when the project has one, and fix what it reports. When a check cannot run in this session, say which one and why, and never report it as passed.
|
|
23
|
+
|
|
24
|
+
**Next:** `.agents/skills/sdlc/playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
|
|
25
|
+
|
|
26
|
+
## Template
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
# Plan: <title>
|
|
30
|
+
|
|
31
|
+
From `intent/<change>/spec.md`.
|
|
32
|
+
|
|
33
|
+
## Files that change
|
|
34
|
+
|
|
35
|
+
## Order of work
|
|
36
|
+
|
|
37
|
+
## Risks
|
|
38
|
+
|
|
39
|
+
## Proof
|
|
40
|
+
```
|
|
@@ -16,7 +16,7 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
16
16
|
4. Commit `spec.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests. Put the areas of concern first in the pull request's description, under the template's first heading. When you cannot open a pull request from this session, say so and give the pushed branch's name.
|
|
17
17
|
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, accepts the spec by setting `Status: accepted.` and merging the pull request, or rejects it by closing it; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
|
|
18
18
|
|
|
19
|
-
**Next:**
|
|
19
|
+
**Next:** `.agents/skills/sdlc/playbooks/build.md`; an engineer with an agent; when the product owner has merged the spec's pull request and the engineer sends `/sdlc build` with the spec's path.
|
|
20
20
|
|
|
21
21
|
## Template
|
|
22
22
|
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Open the pull request
|
|
2
|
+
|
|
3
|
+
The `build` playbook ends here. Nothing in it stops for a person.
|
|
4
|
+
|
|
5
|
+
1. Clean the diff against the default branch. Remove debug output, commented-out code, changes the plan does not name, and comments that `.agents/rules/code-comments.md` does not allow.
|
|
6
|
+
2. Do what `AGENTS.md` and `CONTRIBUTING.md` require of every change, such as a release note.
|
|
7
|
+
3. When step 1 or 2 changed a file, run the checks under **Verifying your work** in `AGENTS.md` again. When one fails, fix the code and run it again. Commit only when they pass.
|
|
8
|
+
4. Push the branch and open the pull request ready for review, as `AGENTS.md` says for branches and pull requests. When the branch already has a pull request, update that one. Fill the body from `.github/pull_request_template.md`:
|
|
9
|
+
- what changed and why, with the paths of `intent/<change>/spec.md` and `plan.md`;
|
|
10
|
+
- `Closes #<issue>` for each issue the change closes, or the word the template asks for when there is none;
|
|
11
|
+
- each check you ran, with its result copied from the output.
|
|
12
|
+
|
|
13
|
+
When you cannot open a pull request from this session, say so and give the pushed branch's name. When you cannot push either, say so; the review then reads the local branch's diff.
|
|
14
|
+
|
|
15
|
+
**Next:** `.agents/skills/sdlc/playbooks/review.md`; an agent; in the same turn, as soon as step 4 is done.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Review phase: review the pull request and drive it to green
|
|
2
|
+
|
|
3
|
+
1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
|
|
4
|
+
2. Review with a fresh context. Start a subagent that has not seen the work, and give it only the diff, `REVIEW.md`, and the change's `intent/<change>/spec.md` and `plan.md`. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. When the project has no `REVIEW.md`, run three passes: bugs, security, and whether the change matches its spec and plan. A change with no `spec.md` or no `plan.md` is itself a finding.
|
|
5
|
+
3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge.
|
|
6
|
+
4. On a pull request or a branch that this session did not create, skip steps 4 and 5: change nothing and push nothing. Otherwise, fix every Important finding and every Nit that is correct, run the checks under **Verifying your work** in `AGENTS.md`, and push. Answer each finding you do not fix with the reason.
|
|
7
|
+
5. Sweep the pull request: read every unresolved review comment and every failing check, fix what each one reports, push, and answer the comment. Repeat until every check passes and no comment is unanswered. Never skip, disable, or weaken a test to pass a check. When a review flags the same mistake a second time, add the correction to `AGENTS.md` under **Things Claude gets wrong** in the same push. When a check fails for a cause outside this change, such as an outage, say which check and why in one comment, and go to step 6.
|
|
8
|
+
6. **Gate: a code owner approves the pull request, and a person merges it.** You never approve it and never merge it. Report the pull request's URL, or the branch's name when there is none, and that it waits only on the code owner. When a new comment or a failing check arrives, go back to step 5.
|
|
9
|
+
|
|
10
|
+
**Next:** none; the project's deploy workflow; when the pull request is merged.
|
|
@@ -10,16 +10,18 @@ Do these steps in order.
|
|
|
10
10
|
|
|
11
11
|
1. **Match the request** to the first row that fits, and read that row's file before you act.
|
|
12
12
|
|
|
13
|
-
| The request | What to do
|
|
14
|
-
| :------------------------------------------------------------------------------- |
|
|
15
|
-
| A question, or a request to explain or check without changing things | Follow [`playbooks/question.md`](playbooks/question.md).
|
|
16
|
-
| An idea, a problem, a ticket, or an incident, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md).
|
|
17
|
-
| A spec for an intent
|
|
18
|
-
| A
|
|
13
|
+
| The request | What to do |
|
|
14
|
+
| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
|
|
15
|
+
| A question, or a request to explain or check without changing things | Follow [`playbooks/question.md`](playbooks/question.md). |
|
|
16
|
+
| An idea, a problem, a ticket, or an incident, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md). |
|
|
17
|
+
| A spec for an intent, or a path to an `intent.md` | Follow [`playbooks/design.md`](playbooks/design.md). |
|
|
18
|
+
| A build for a spec, a path to a `spec.md`, or a plan the engineer accepted | Follow [`playbooks/build.md`](playbooks/build.md). |
|
|
19
|
+
| A review of a pull request, or a pull request to drive to green | Follow [`playbooks/review.md`](playbooks/review.md). |
|
|
20
|
+
| A later step: a deploy or an incident fix | Say "This step has no playbook in `/sdlc` yet" and name the step. Answer what you can as `playbooks/question.md` says, and stop. |
|
|
19
21
|
|
|
20
22
|
When a request both asks a question and reports a problem, use `question` and offer `plan` in one line.
|
|
21
23
|
|
|
22
|
-
2. **Do the playbook's steps yourself.** Find facts in files and commands instead of asking. Stop only where the playbook says to stop; at a step marked **Gate**, which waits for the person it names and is never skipped; before an irreversible action; or for a decision no file settles. `.agents/rules/agent-owned-work.md` lists the gates and the irreversible actions.
|
|
24
|
+
2. **Do the playbook's steps yourself.** Find facts in files and commands instead of asking. Stop only where the playbook says to stop; at a step marked **Gate**, which waits for the person it names and is never skipped; before an irreversible action; or for a decision no file settles. `.agents/rules/agent-owned-work.md` lists the gates and the irreversible actions. When a playbook's **Next** line says an agent runs the next file in the same turn, read that file and continue without asking.
|
|
23
25
|
3. **Write the reply in the shape below,** following the **Write replies a person can check** convention in `AGENTS.md`.
|
|
24
26
|
|
|
25
27
|
## Reply shape
|
|
@@ -39,7 +41,7 @@ Write every part in the language of the person's message; keep paths, commands,
|
|
|
39
41
|
**Status:** <what is done, what comes next, and which gate it waits on and for whom.>
|
|
40
42
|
```
|
|
41
43
|
|
|
42
|
-
A step that is not finished is `open`, including one that waits at its Gate. Use `skip` only for a step you decide never to do.
|
|
44
|
+
A step that is not finished is `open`, including one that waits at its Gate. When one turn runs more than one playbook, list the steps of each under the playbook's file name. Use `skip` only for a step you decide never to do.
|
|
43
45
|
|
|
44
46
|
When the evidence shows that the change cannot be made in this project, say so under **Request**. In the `plan` playbook, the first round then asks the one question that settles where the change belongs.
|
|
45
47
|
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Build phase: plan, then implement
|
|
2
|
+
|
|
3
|
+
This playbook turns a merged spec into a plan the engineer accepts, and then into working code.
|
|
4
|
+
|
|
5
|
+
1. Find the change: the `intent/<change>/` folder whose `spec.md` or `plan.md` the request names. Its `spec.md` must be on the default branch beside its `intent.md`. In each case below, say only that, in two or three lines, and stop: write no file.
|
|
6
|
+
- The request names no change, or the folder has no `spec.md` on any branch: list each `intent/*/` on the default branch that has a `spec.md` and no `plan.md`, or say that there is none.
|
|
7
|
+
- The spec exists only on another branch: say that the spec is not merged yet, and name that branch.
|
|
8
|
+
- `intent/<change>/plan.md` is already on the default branch: say that the change is built, and name the file.
|
|
9
|
+
2. When `intent/<change>/plan.md` exists on a branch that is not merged, check out that branch. When the request says the plan is accepted, go to step 7. Otherwise show that plan and go to step 5.
|
|
10
|
+
3. Read `intent.md`, `spec.md`, and the code the change touches.
|
|
11
|
+
4. Write the plan from the template below, in the language of the files already in `intent/`. Use exactly the template's headings. An engineer who has never seen this conversation must be able to implement the change from the plan alone.
|
|
12
|
+
- **Files that change:** every file, marked new, changed, or deleted, with one line on what it does afterwards.
|
|
13
|
+
- **Order of work:** numbered steps; each ends with the check that proves it.
|
|
14
|
+
- **Risks:** what the change could break, which step is the riskiest, and each option you chose not to take and why.
|
|
15
|
+
- **Proof:** the tests and commands that show every requirement of the spec is met, by requirement number.
|
|
16
|
+
|
|
17
|
+
Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file: show the plan as the plan.
|
|
18
|
+
|
|
19
|
+
5. **Gate: the engineer accepts the plan.** Ask whether an engineer could build from it, and revise until they say yes. Change no code and commit nothing before that yes. In plan mode, the engineer approving the plan is that yes. When the spec or `AGENTS.md` classes the change as higher risk, say that a tech lead or an architect accepts the plan with the engineer.
|
|
20
|
+
6. Create the branch as `AGENTS.md` says, and commit `intent/<change>/plan.md` as its first commit.
|
|
21
|
+
7. Implement the plan in its order. After each step, run the check that proves it and fix what fails. For a bug fix, first write the test that reproduces the bug, run it, check that it fails for the reason you expect, and commit it. Then create `.git/bug-fix-in-progress`, make the test pass without editing it, and delete `.git/bug-fix-in-progress`. When the work departs from the plan, change `plan.md` in the same commit.
|
|
22
|
+
8. Run every check under **Verifying your work** in `AGENTS.md` and keep the output. Every check must pass: fix the code, and never skip, delete, or weaken a test. Then run the `verifier` subagent when the project has one, and fix what it reports. When a check cannot run in this session, say which one and why, and never report it as passed.
|
|
23
|
+
|
|
24
|
+
**Next:** `.agents/skills/sdlc/playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
|
|
25
|
+
|
|
26
|
+
## Template
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
# Plan: <title>
|
|
30
|
+
|
|
31
|
+
From `intent/<change>/spec.md`.
|
|
32
|
+
|
|
33
|
+
## Files that change
|
|
34
|
+
|
|
35
|
+
## Order of work
|
|
36
|
+
|
|
37
|
+
## Risks
|
|
38
|
+
|
|
39
|
+
## Proof
|
|
40
|
+
```
|
|
@@ -16,7 +16,7 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
16
16
|
4. Commit `spec.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests. Put the areas of concern first in the pull request's description, under the template's first heading. When you cannot open a pull request from this session, say so and give the pushed branch's name.
|
|
17
17
|
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, accepts the spec by setting `Status: accepted.` and merging the pull request, or rejects it by closing it; you do neither. Report the pull request's URL, keep it green as `AGENTS.md` says, and wait.
|
|
18
18
|
|
|
19
|
-
**Next:**
|
|
19
|
+
**Next:** `.agents/skills/sdlc/playbooks/build.md`; an engineer with an agent; when the product owner has merged the spec's pull request and the engineer sends `/sdlc build` with the spec's path.
|
|
20
20
|
|
|
21
21
|
## Template
|
|
22
22
|
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Open the pull request
|
|
2
|
+
|
|
3
|
+
The `build` playbook ends here. Nothing in it stops for a person.
|
|
4
|
+
|
|
5
|
+
1. Clean the diff against the default branch. Remove debug output, commented-out code, changes the plan does not name, and comments that `.agents/rules/code-comments.md` does not allow.
|
|
6
|
+
2. Do what `AGENTS.md` and `CONTRIBUTING.md` require of every change, such as a release note.
|
|
7
|
+
3. When step 1 or 2 changed a file, run the checks under **Verifying your work** in `AGENTS.md` again. When one fails, fix the code and run it again. Commit only when they pass.
|
|
8
|
+
4. Push the branch and open the pull request ready for review, as `AGENTS.md` says for branches and pull requests. When the branch already has a pull request, update that one. Fill the body from `.github/pull_request_template.md`:
|
|
9
|
+
- what changed and why, with the paths of `intent/<change>/spec.md` and `plan.md`;
|
|
10
|
+
- `Closes #<issue>` for each issue the change closes, or the word the template asks for when there is none;
|
|
11
|
+
- each check you ran, with its result copied from the output.
|
|
12
|
+
|
|
13
|
+
When you cannot open a pull request from this session, say so and give the pushed branch's name. When you cannot push either, say so; the review then reads the local branch's diff.
|
|
14
|
+
|
|
15
|
+
**Next:** `.agents/skills/sdlc/playbooks/review.md`; an agent; in the same turn, as soon as step 4 is done.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Review phase: review the pull request and drive it to green
|
|
2
|
+
|
|
3
|
+
1. Find what to review: the pull request this session just opened, or the pull request or branch the request names. When there is no pull request, or this session cannot reach its host, review the branch's diff against the default branch and put the findings in your reply in place of a comment.
|
|
4
|
+
2. Review with a fresh context. Start a subagent that has not seen the work, and give it only the diff, `REVIEW.md`, and the change's `intent/<change>/spec.md` and `plan.md`. When you cannot start a subagent, read the diff again from the first line as if someone else wrote it. The review runs each pass in `REVIEW.md` and reports each finding with its pass, **Important** or **Nit**, `path:line`, and the evidence. When the project has no `REVIEW.md`, run three passes: bugs, security, and whether the change matches its spec and plan. A change with no `spec.md` or no `plan.md` is itself a finding.
|
|
5
|
+
3. Post the findings as one comment on the pull request, most severe first. Write "No findings" when there are none. A finding does not decide the merge.
|
|
6
|
+
4. On a pull request or a branch that this session did not create, skip steps 4 and 5: change nothing and push nothing. Otherwise, fix every Important finding and every Nit that is correct, run the checks under **Verifying your work** in `AGENTS.md`, and push. Answer each finding you do not fix with the reason.
|
|
7
|
+
5. Sweep the pull request: read every unresolved review comment and every failing check, fix what each one reports, push, and answer the comment. Repeat until every check passes and no comment is unanswered. Never skip, disable, or weaken a test to pass a check. When a review flags the same mistake a second time, add the correction to `AGENTS.md` under **Things Claude gets wrong** in the same push. When a check fails for a cause outside this change, such as an outage, say which check and why in one comment, and go to step 6.
|
|
8
|
+
6. **Gate: a code owner approves the pull request, and a person merges it.** You never approve it and never merge it. Report the pull request's URL, or the branch's name when there is none, and that it waits only on the code owner. When a new comment or a failing check arrives, go back to step 5.
|
|
9
|
+
|
|
10
|
+
**Next:** none; the project's deploy workflow; when the pull request is merged.
|
package/templates/base/SETUP.md
CHANGED
|
@@ -6,7 +6,7 @@ This project follows Anthropic's [AI-native SDLC Playbook](https://claude.com/re
|
|
|
6
6
|
|
|
7
7
|
1. **Plan:** the originator of an idea, a ticket, or an incident sends it with `/sdlc`, which interviews them and writes `intent/<change>/intent.md`. The product owner accepts it by merging it with `Status: accepted.`, or rejects it by closing its pull request.
|
|
8
8
|
2. **Design:** `spec.md` is written from the accepted intent with the policy skills loaded (send the intent's path with `/sdlc`). The product owner resolves concerns with the policy owners.
|
|
9
|
-
3. **Build:** the engineer starts in plan mode, approves the plan, and commits it as `plan.md`. A tech lead approves higher-risk plans.
|
|
9
|
+
3. **Build:** the engineer sends `/sdlc build` with the spec's path, starts in plan mode, approves the plan, and commits it as `plan.md`. A tech lead approves higher-risk plans.
|
|
10
10
|
4. **Test:** the session runs **Verifying your work** in `AGENTS.md`.
|
|
11
11
|
5. **Review:** Claude Code Review and Bugbot review by `REVIEW.md`. A code owner approves; the agent never does.
|
|
12
12
|
6. **Deploy:** once `DEPLOY_ENABLED` is `true`, each push to `main` that passes CI deploys to `dev`, and the Deploy workflow promotes a commit to `uat` and then `prod`. `agent-production-gate.sh` blocks an agent's shell commands that deploy to `prod`, run a Railway command with `prod` as its environment, or push a release tag, unless a release manager started the session with `RELEASE_APPROVAL` set.
|
|
@@ -5,7 +5,7 @@ This folder is the intent home. Every change starts here as an `intent.md`, and
|
|
|
5
5
|
- Each change has its own folder, `intent/<change>/`, where `<change>` is a short kebab-case name. The folder holds `intent.md` (Plan), then `spec.md` (Design), then `plan.md` (Build).
|
|
6
6
|
- **Plan.** An idea, a ticket, or an incident becomes `intent.md`, written by sending the idea with `/sdlc`, which interviews the originator. The originator corrects the draft before it is committed, and the product owner reviews it in its pull request. Merging its pull request records the decision: `Status: accepted.` accepts it, and `Status: rejected.` rejects it.
|
|
7
7
|
- **Design.** Sending the intent's path with `/sdlc` turns the accepted `intent.md` into `spec.md`, committed alongside it. The product owner reviews the spec against the idea and resolves each area of concern with its policy owner. Accepting the spec starts the build.
|
|
8
|
-
- **Build.** The engineer starts in plan mode with `intent.md` and `spec.md`, and commits the approved plan as `plan.md`. When implementation departs from the plan, `plan.md` changes in the same commit.
|
|
8
|
+
- **Build.** The engineer sends `/sdlc build` with the spec's path, starts in plan mode with `intent.md` and `spec.md`, and commits the approved plan as `plan.md`. When implementation departs from the plan, `plan.md` changes in the same commit.
|
|
9
9
|
|
|
10
10
|
## Which file holds what
|
|
11
11
|
|
|
@@ -37,7 +37,7 @@ If a test fails, fix the code, not the test.
|
|
|
37
37
|
5. **Start from the accepted spec, in plan mode.** Claude Code starts every session in plan mode (`.claude/settings.json`); in Cursor, switch to Plan Mode before the first edit. Give the plan the change's `intent/<change>/intent.md` and `spec.md`, and have it name the files that change, the order of the work, and the tests that prove it. Commit the approved plan as `intent/<change>/plan.md`. When implementation departs from the plan, update `plan.md` in the same commit.
|
|
38
38
|
6. **Start a bug fix with a failing test.** Reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, and make the test pass without editing it. Delete `.git/bug-fix-in-progress` when the fix is done.
|
|
39
39
|
7. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
|
|
40
|
-
8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `
|
|
40
|
+
8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
|
|
41
41
|
9. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
|
|
42
42
|
|
|
43
43
|
## Things Claude gets wrong
|
|
@@ -37,7 +37,7 @@ If a test fails, fix the code, not the test.
|
|
|
37
37
|
5. **Start from the accepted spec, in plan mode.** Claude Code starts every session in plan mode (`.claude/settings.json`); in Cursor, switch to Plan Mode before the first edit. Give the plan the change's `intent/<change>/intent.md` and `spec.md`, and have it name the files that change, the order of the work, and the tests that prove it. Commit the approved plan as `intent/<change>/plan.md`. When implementation departs from the plan, update `plan.md` in the same commit.
|
|
38
38
|
6. **Start a bug fix with a failing test.** Reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, and make the test pass without editing it. Delete `.git/bug-fix-in-progress` when the fix is done.
|
|
39
39
|
7. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
|
|
40
|
-
8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `
|
|
40
|
+
8. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
|
|
41
41
|
9. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
|
|
42
42
|
|
|
43
43
|
## Things Claude gets wrong
|
|
@@ -35,7 +35,7 @@ If a test fails, fix the code, not the test.
|
|
|
35
35
|
4. **Start from the accepted spec, in plan mode.** Claude Code starts every session in plan mode (`.claude/settings.json`); in Cursor, switch to Plan Mode before the first edit. Give the plan the change's `intent/<change>/intent.md` and `spec.md`, and have it name the files that change, the order of the work, and the tests that prove it. Commit the approved plan as `intent/<change>/plan.md`. When implementation departs from the plan, update `plan.md` in the same commit.
|
|
36
36
|
5. **Start a bug fix with a failing test.** Reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, and make the test pass without editing it. Delete `.git/bug-fix-in-progress` when the fix is done.
|
|
37
37
|
6. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
|
|
38
|
-
7. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `
|
|
38
|
+
7. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
|
|
39
39
|
8. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
|
|
40
40
|
|
|
41
41
|
## Things Claude gets wrong
|
|
@@ -40,7 +40,7 @@ If a test fails, fix the code, not the test.
|
|
|
40
40
|
6. **Start from the accepted spec, in plan mode.** Claude Code starts every session in plan mode (`.claude/settings.json`); in Cursor, switch to Plan Mode before the first edit. Give the plan the change's `intent/<change>/intent.md` and `spec.md`, and have it name the files that change, the order of the work, and the tests that prove it. Commit the approved plan as `intent/<change>/plan.md`. When implementation departs from the plan, update `plan.md` in the same commit.
|
|
41
41
|
7. **Start a bug fix with a failing test.** Reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, and make the test pass without editing it. Delete `.git/bug-fix-in-progress` when the fix is done.
|
|
42
42
|
8. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
|
|
43
|
-
9. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `
|
|
43
|
+
9. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
|
|
44
44
|
10. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
|
|
45
45
|
|
|
46
46
|
## Things Claude gets wrong
|
|
@@ -42,7 +42,7 @@ If a test fails, fix the code, not the test.
|
|
|
42
42
|
6. **Start from the accepted spec, in plan mode.** Claude Code starts every session in plan mode (`.claude/settings.json`); in Cursor, switch to Plan Mode before the first edit. Give the plan the change's `intent/<change>/intent.md` and `spec.md`, and have it name the files that change, the order of the work, and the tests that prove it. Commit the approved plan as `intent/<change>/plan.md`. When implementation departs from the plan, update `plan.md` in the same commit.
|
|
43
43
|
7. **Start a bug fix with a failing test.** Reproduce the bug as a test, run it, and confirm it fails for the reason you expect. Commit that test. Then create `.git/bug-fix-in-progress`, so `.agents/hooks/agent-test-edit-gate.sh` blocks test edits, and make the test pass without editing it. Delete `.git/bug-fix-in-progress` when the fix is done.
|
|
44
44
|
8. **Start work only when a person asks or a trigger runs it, and stop only at the human gates, before an irreversible action, or for a decision only a person can make.** A question or a statement gets an answer, not a file, a commit, or a pull request. When a message reports a problem without asking for work, answer in a few lines and end with the message that would start the work: `/sdlc` followed by their own words. Once a task starts, carry it to the next gate without asking; `.agents/rules/agent-owned-work.md` lists the gates.
|
|
45
|
-
9. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `
|
|
45
|
+
9. **Branch from the latest `origin/main`, and open the pull request ready for review.** Name the branch `<type>/<short-description>` and fill the body from `.github/pull_request_template.md`. `.github/workflows/ci.yml` runs full verification only on a pull request that is not a draft. Drive it until it is green and waits only on code owner approval, as `.agents/skills/sdlc/playbooks/review.md` describes. Rebase and `git push --force-with-lease` only branches you own. Never merge a pull request: a person merges it with `--squash` after code owner approval, bottom-up for a stack of pull requests.
|
|
46
46
|
10. **Write replies a person can check.** Reply in the language the person wrote in. Write paths from the project root, such as `README.md:12`, never from the machine's root. State as a fact only what you opened or ran in this turn, and say what you ran; mark anything else as inferred or not checked. Answer what was asked and stop: leave out tools, services, and steps the request does not need, and never hand the person a check you could run. Send nothing outside the session, such as a message to another session or a service, unless a task step says to.
|
|
47
47
|
|
|
48
48
|
## Things Claude gets wrong
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: babysit-pr
|
|
3
|
-
description: Drive a pull request you opened until it waits only on code owner approval. Use right after you open a pull request, or when a person asks you to babysit one.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Babysit a pull request
|
|
7
|
-
|
|
8
|
-
Sweep the unresolved review comments and failing checks on the pull request, address them, and push the fixes. Repeat until the pull request is green and waiting only on code owner approval. Never approve or merge it.
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: babysit-pr
|
|
3
|
-
description: Drive a pull request you opened until it waits only on code owner approval. Use right after you open a pull request, or when a person asks you to babysit one.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Babysit a pull request
|
|
7
|
-
|
|
8
|
-
Sweep the unresolved review comments and failing checks on the pull request, address them, and push the fixes. Repeat until the pull request is green and waiting only on code owner approval. Never approve or merge it.
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: babysit-pr
|
|
3
|
-
description: Drive a pull request you opened until it waits only on code owner approval. Use right after you open a pull request, or when a person asks you to babysit one.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Babysit a pull request
|
|
7
|
-
|
|
8
|
-
Sweep the unresolved review comments and failing checks on the pull request, address them, and push the fixes. Repeat until the pull request is green and waiting only on code owner approval. Never approve or merge it.
|