@next-friday/create-app 9.0.0 → 9.1.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 +4 -2
- package/templates/base/.agents/review.md +1 -1
- package/templates/base/.agents/skills/sdlc/SKILL.md +14 -12
- package/templates/base/.agents/skills/sdlc/playbooks/build.md +10 -9
- package/templates/base/.agents/skills/sdlc/playbooks/deploy.md +9 -0
- package/templates/base/.agents/skills/sdlc/playbooks/design.md +8 -5
- package/templates/base/.agents/skills/sdlc/playbooks/maintain.md +21 -0
- package/templates/base/.agents/skills/sdlc/playbooks/open-pr.md +4 -4
- package/templates/base/.agents/skills/sdlc/playbooks/plan.md +5 -5
- package/templates/base/.agents/skills/sdlc/playbooks/review.md +12 -5
- package/templates/base/.agents/skills/sdlc-help/SKILL.md +4 -5
- package/templates/base/.claude/skills/sdlc/SKILL.md +14 -12
- package/templates/base/.claude/skills/sdlc/playbooks/build.md +10 -9
- package/templates/base/.claude/skills/sdlc/playbooks/deploy.md +9 -0
- package/templates/base/.claude/skills/sdlc/playbooks/design.md +8 -5
- package/templates/base/.claude/skills/sdlc/playbooks/maintain.md +21 -0
- package/templates/base/.claude/skills/sdlc/playbooks/open-pr.md +4 -4
- package/templates/base/.claude/skills/sdlc/playbooks/plan.md +5 -5
- package/templates/base/.claude/skills/sdlc/playbooks/review.md +12 -5
- package/templates/base/.claude/skills/sdlc-help/SKILL.md +4 -5
- package/templates/base/.cursor/skills/sdlc/SKILL.md +14 -12
- package/templates/base/.cursor/skills/sdlc/playbooks/build.md +10 -9
- package/templates/base/.cursor/skills/sdlc/playbooks/deploy.md +9 -0
- package/templates/base/.cursor/skills/sdlc/playbooks/design.md +8 -5
- package/templates/base/.cursor/skills/sdlc/playbooks/maintain.md +21 -0
- package/templates/base/.cursor/skills/sdlc/playbooks/open-pr.md +4 -4
- package/templates/base/.cursor/skills/sdlc/playbooks/plan.md +5 -5
- package/templates/base/.cursor/skills/sdlc/playbooks/review.md +12 -5
- package/templates/base/.cursor/skills/sdlc-help/SKILL.md +4 -5
- package/templates/base/.github/ISSUE_TEMPLATE/documentation.yml +25 -0
- package/templates/base/REVIEW.md +1 -1
- package/templates/base/SECURITY.md +1 -1
- package/templates/base/SETUP.md +9 -13
- package/templates/base/bands.yaml +2 -3
- package/templates/base/intent/README.md +2 -4
- package/templates/base/lessons/README.md +5 -0
- package/templates/base/scripts/check-intent.ts +391 -0
- package/templates/nestjs/.github/workflows/ci.yml +2 -0
- package/templates/nestjs/AGENTS.md +9 -17
- package/templates/nestjs/CONTRIBUTING.md +1 -0
- package/templates/nestjs/package.json +2 -1
- package/templates/nextjs/.github/workflows/ci.yml +2 -0
- package/templates/nextjs/AGENTS.md +9 -17
- package/templates/nextjs/CONTRIBUTING.md +1 -0
- package/templates/nextjs/package.json +2 -1
- package/templates/nodejs/.github/workflows/ci.yml +2 -0
- package/templates/nodejs/AGENTS.md +8 -16
- package/templates/nodejs/CONTRIBUTING.md +1 -0
- package/templates/nodejs/package.json +2 -1
- package/templates/payload/.github/workflows/ci.yml +2 -0
- package/templates/payload/AGENTS.md +10 -18
- package/templates/payload/CONTRIBUTING.md +1 -0
- package/templates/payload/package.json +2 -1
- package/templates/turborepo/.github/workflows/ci.yml +2 -0
- package/templates/turborepo/AGENTS.md +10 -18
- package/templates/turborepo/CONTRIBUTING.md +1 -0
- package/templates/turborepo/package.json +2 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@next-friday/create-app",
|
|
3
|
-
"version": "9.
|
|
3
|
+
"version": "9.1.0",
|
|
4
4
|
"description": "Create a Next Friday project from a template.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"create",
|
|
@@ -68,6 +68,7 @@
|
|
|
68
68
|
"build": "tsdown",
|
|
69
69
|
"changeset": "changeset",
|
|
70
70
|
"changeset:status": "changeset status --since main",
|
|
71
|
+
"changesets:check": "node scripts/check-changesets.ts",
|
|
71
72
|
"check:publint": "publint",
|
|
72
73
|
"clean": "rm -rf dist coverage *.tsbuildinfo .eslintcache node_modules/.cache",
|
|
73
74
|
"dev": "tsdown --watch",
|
|
@@ -75,6 +76,7 @@
|
|
|
75
76
|
"format:check": "prettier --check --cache . && editorconfig-checker",
|
|
76
77
|
"gates:check": "node scripts/check-agent-gates.ts",
|
|
77
78
|
"human-gates:check": "node scripts/check-human-gates.ts",
|
|
79
|
+
"intent:check": "node scripts/check-intent.ts",
|
|
78
80
|
"knip": "knip",
|
|
79
81
|
"lint": "eslint . --fix --cache --max-warnings=0 --no-inline-config",
|
|
80
82
|
"lint:check": "eslint . --cache --max-warnings=0 --no-inline-config",
|
|
@@ -87,6 +89,6 @@
|
|
|
87
89
|
"test:coverage": "vitest run --coverage",
|
|
88
90
|
"test:watch": "vitest",
|
|
89
91
|
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
90
|
-
"verify": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm typecheck && pnpm test:coverage && pnpm knip && pnpm build && pnpm check:publint"
|
|
92
|
+
"verify": "pnpm suppressions:check && pnpm rules:check && pnpm gates:check && pnpm human-gates:check && pnpm intent:check && pnpm changesets:check && pnpm lint:check && pnpm format:check && pnpm sort-package-json:check && pnpm typecheck && pnpm test:coverage && pnpm knip && pnpm build && pnpm check:publint"
|
|
91
93
|
}
|
|
92
94
|
}
|
|
@@ -6,7 +6,7 @@ Run three passes and tag each finding with its pass:
|
|
|
6
6
|
|
|
7
7
|
- Bugs: logic errors, broken edge cases, subtle regressions
|
|
8
8
|
- Security: injection risks, authentication gaps, PII in logs
|
|
9
|
-
- Compliance: the change matches spec.md, plan.md and our design principles
|
|
9
|
+
- Compliance: the change matches spec.md, plan.md and our design principles; flag a plan.md that has no `Accepted by:` line
|
|
10
10
|
|
|
11
11
|
## What Important means here
|
|
12
12
|
|
|
@@ -10,23 +10,25 @@ 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
|
|
14
|
-
|
|
|
15
|
-
| A question, or a request to explain or check without changing things
|
|
16
|
-
|
|
|
17
|
-
| A
|
|
18
|
-
| A
|
|
19
|
-
| A
|
|
20
|
-
| 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
|
+
| A spec for an intent, or a path to an `intent.md` | Follow [`playbooks/design.md`](playbooks/design.md). |
|
|
17
|
+
| A build for a spec, a path to a `spec.md`, or a plan the engineer accepted | Follow [`playbooks/build.md`](playbooks/build.md). |
|
|
18
|
+
| A review of a pull request or a branch, a failing check on a pull request, or a pull request to drive to green | Follow [`playbooks/review.md`](playbooks/review.md). |
|
|
19
|
+
| A deploy, a promotion to an environment, or a release to production | Follow [`playbooks/deploy.md`](playbooks/deploy.md). |
|
|
20
|
+
| A finding sent by a job, a monitor, or a trigger, or one the message says no person can answer questions about | Follow [`playbooks/maintain.md`](playbooks/maintain.md). |
|
|
21
|
+
| An idea, a problem, a ticket, or an incident that a person describes, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md). |
|
|
22
|
+
| Anything else | Say which of the rows above is closest and why it does not fit, answer what you can as `playbooks/question.md` says, and stop. |
|
|
21
23
|
|
|
22
24
|
When a request both asks a question and reports a problem, use `question` and offer `plan` in one line.
|
|
23
25
|
|
|
24
|
-
2. **Do the playbook's steps yourself
|
|
25
|
-
3. **Write the reply in the shape below
|
|
26
|
+
2. **Do the playbook's steps yourself,** stopping only as `.agents/rules/agent-owned-work.md` says. At a step marked **Gate**, wait for the person it names. When a playbook's **Next** line says an agent runs the next file in the same turn, read that file and continue without asking.
|
|
27
|
+
3. **Write the reply in the shape below.**
|
|
26
28
|
|
|
27
29
|
## Reply shape
|
|
28
30
|
|
|
29
|
-
|
|
31
|
+
Reply in the language the person wrote in, even when the message also holds a command, a path, or English technical terms. Only paths, commands, copied step text, and a draft file's own text stay as they are. For `question` and for a request no row fits, leave out **Steps** and put the answer in its place.
|
|
30
32
|
|
|
31
33
|
```markdown
|
|
32
34
|
**Request:** <the goal, the problem it solves, and the smallest change you expect to meet it, in your own words. When you cannot name the smallest change yet, say what you must learn first. For a question, only the question.>
|
|
@@ -41,7 +43,7 @@ Write every part in the language of the person's message; keep paths, commands,
|
|
|
41
43
|
**Status:** <what is done, what comes next, and which gate it waits on and for whom.>
|
|
42
44
|
```
|
|
43
45
|
|
|
44
|
-
A step that is not finished is `open`, including one
|
|
46
|
+
A step that is not finished is `open`, including one at its Gate. When one turn runs more than one playbook, list the steps of each under its file name. A reply that ends before a **Gate** step says which step stopped it and why. "Waiting for an instruction" is not a reason. Use `skip` only for a step you decide never to do.
|
|
45
47
|
|
|
46
48
|
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.
|
|
47
49
|
|
|
@@ -8,27 +8,28 @@ This playbook turns a merged spec into a plan the engineer accepts, and then int
|
|
|
8
8
|
- `intent/<change>/plan.md` is already on the default branch: say that the change is built, and name the file.
|
|
9
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
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.
|
|
11
|
+
4. Write the plan from the template below, in the language of the files already in `intent/`. Use exactly the template's headings. The date in the title is the date of the last commit to `intent/<change>/intent.md`: `git log -1 --format=%cs -- intent/<change>/intent.md`. An engineer who has never seen this conversation must be able to implement the change from the plan alone.
|
|
12
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
|
|
13
|
+
- **Order of work:** numbered steps. Each ends with the check that proves it.
|
|
14
14
|
- **Risks:** what the change could break, which step is the riskiest, and each option you chose not to take and why.
|
|
15
15
|
- **Proof:** the tests and commands that show every requirement of the spec is met, by requirement number.
|
|
16
16
|
|
|
17
|
-
Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file
|
|
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
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,
|
|
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,
|
|
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
|
|
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, approving the plan is that yes. When the spec 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. Set the plan's `Accepted by:` line, under its title, to the engineer who said yes in step 5, 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, follow **Start a bug fix with a failing test** in `AGENTS.md`. 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 look for `.claude/agents/verifier.md`: when it exists, run the `verifier` subagent and fix what it reports; when you cannot start a subagent, do what that file says yourself. When a check cannot run in this session, say which one and why, and never report it as passed.
|
|
23
|
+
9. Go on in the same turn, without asking: follow `.agents/skills/sdlc/playbooks/open-pr.md`, and then `.agents/skills/sdlc/playbooks/review.md`. Pushing the branch and opening the pull request are part of this task.
|
|
23
24
|
|
|
24
25
|
**Next:** `.agents/skills/sdlc/playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
|
|
25
26
|
|
|
26
27
|
## Template
|
|
27
28
|
|
|
28
29
|
```markdown
|
|
29
|
-
# Plan: <title>
|
|
30
|
+
# Plan: <title> (from intent.md <YYYY-MM-DD>)
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
Accepted by: @<engineer>.
|
|
32
33
|
|
|
33
34
|
## Files that change
|
|
34
35
|
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Deploy phase: take a merged change to the production gate
|
|
2
|
+
|
|
3
|
+
1. Find the commit: the full SHA on the default branch that the request names, or the latest commit there. Read its CI run. When a check failed or is still running, say which one in two lines and stop. When you cannot read the CI run from this session, say so and carry on with the commit marked as not verified.
|
|
4
|
+
2. Read how this project deploys: the deploy section of `README.md` and `.github/workflows/deploy.yml`. When the project has no deploy workflow, or deploying is switched off, say so in two lines and stop. When you cannot tell whether deploying is switched on, say so and carry on.
|
|
5
|
+
3. Report where the commit is. For each environment, in the order the project promotes them, say whether this commit is deployed there, and give the deployment's link or the output that shows it. Read production only from the deploy workflow's run history, never with a command that names the production environment. Where you cannot read an environment, write "not read" and why.
|
|
6
|
+
4. Promote the commit to an environment before production only when the request asks for that environment. Do it the way `README.md` says, one environment at a time, and read the health check after each. When a deployment fails, stop: report the failing step and its log, and promote no further. When the request names production, by any name such as `prod`, go to step 5. When it names an environment the project does not have, say so and list the ones it has.
|
|
7
|
+
5. **Gate: the release manager authorizes production.** Never start a production deployment, run a command that names the production environment, or push a release tag. Report the commit's SHA, the environments it has passed, the checks' results, and the exact action the release manager takes to promote it. Then wait.
|
|
8
|
+
|
|
9
|
+
**Next:** `.agents/skills/sdlc/playbooks/maintain.md`; a job or a person; when monitoring or a ticket reports a finding in production.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Design phase: write `spec.md`
|
|
2
2
|
|
|
3
|
-
This playbook turns a merged intent into the requirements and design spec.
|
|
3
|
+
This playbook turns a merged intent into the requirements and design spec.
|
|
4
4
|
|
|
5
5
|
1. Find the intent: the `intent/<change>/intent.md` the request names. It must be on the default branch and have no `spec.md` beside it. In each case below, say only that, in two or three lines, and stop: write no file and add no review of the intent.
|
|
6
6
|
- The request names no intent, or the file does not exist on any branch: list each `intent/*/intent.md` on the default branch that has no `spec.md`, or say that there is none.
|
|
@@ -8,13 +8,14 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
8
8
|
- `spec.md` already exists: say so and name the file.
|
|
9
9
|
2. Read the four policies, every time, before you write: `.agents/skills/brand-policy/SKILL.md`, `.agents/skills/security-policy/SKILL.md`, `.agents/skills/compliance-policy/SKILL.md`, and `.agents/skills/ux-policy/SKILL.md`. Then read the code and the docs the change touches.
|
|
10
10
|
3. Write `intent/<change>/spec.md` from the template below, in the language of the files already in `intent/`. Use exactly the template's headings.
|
|
11
|
-
- **
|
|
11
|
+
- **Request:** under the status line, quote the words of the request that started this spec. Add no date and no commit: git records both.
|
|
12
|
+
- **Requirements:** numbered. Each one states a result a test or a reader can check.
|
|
12
13
|
- **Design:** how the change fits the existing code: the files that change, and what each one does afterwards.
|
|
13
|
-
- **Policies:** one line for each of the four policies
|
|
14
|
-
- **Areas of concern:** a policy rule the change cannot meet, two policies that contradict, or a decision the files do not settle. Give each one a number, the policy it comes from, and that policy's owner from `.github/CODEOWNERS`. When `.github/CODEOWNERS` names no owner for a policy's folder, write "no owner in `.github/CODEOWNERS`" in place of the owner
|
|
14
|
+
- **Policies:** one line for each of the four policies. State which rules of that policy the change must meet, each as a requirement number, or write "Does not apply" and why.
|
|
15
|
+
- **Areas of concern:** a policy rule the change cannot meet, two policies that contradict, or a decision the files do not settle. Give each one a number, the policy it comes from, and that policy's owner from `.github/CODEOWNERS`. When `.github/CODEOWNERS` names no owner for a policy's folder, write "no owner in `.github/CODEOWNERS`" in place of the owner. Add one area of concern that says so. Write "None" only when there are none.
|
|
15
16
|
- **Open questions:** each open question from `intent.md`, answered with its evidence or carried forward. Write "None" only when the intent has none.
|
|
16
17
|
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
|
-
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, accepts the spec
|
|
18
|
+
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, then accepts the spec (`Status: accepted.` and merge) or rejects it (close). You do neither. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
|
|
18
19
|
|
|
19
20
|
**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
21
|
|
|
@@ -25,6 +26,8 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
25
26
|
|
|
26
27
|
From `intent/<change>/intent.md`. Status: draft.
|
|
27
28
|
|
|
29
|
+
Request: "<the words of the request that started this spec>".
|
|
30
|
+
|
|
28
31
|
## Requirements
|
|
29
32
|
|
|
30
33
|
## Design
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Maintain phase: turn a finding into `intent.md`
|
|
2
|
+
|
|
3
|
+
This playbook starts from a finding such as an alert, a monitoring ticket, a failing run, or an incident. No one answers questions while it runs.
|
|
4
|
+
|
|
5
|
+
1. Read the finding the request gives: what was seen, where, when, and its link or log. When the request gives no finding, say so in two lines and stop. When the finding asks for a new capability and reports no fault, say that a person sends it with `/sdlc`, and stop.
|
|
6
|
+
2. Diagnose without changing anything. Read the logs, the code, and the changes merged before the finding. When `bands.yaml` names the tools for the finding's tier, use only those. Write no file outside `intent/`, start no deploy, and run no runbook that `bands.yaml` does not list for that tier. When the finding names no tier, or the project has no `bands.yaml`, use read-only tools only. When the tier's action is only to log, put the finding in your reply and stop.
|
|
7
|
+
3. Write `intent/<change>/intent.md` from the template in `.agents/skills/sdlc/playbooks/plan.md`, in the language of the files already in `intent/`. Use exactly the template's five headings.
|
|
8
|
+
- **Problem:** the anomaly and its evidence: the number, its source, and the time.
|
|
9
|
+
- **Proposed outcome:** what the fixed system does, as its user would see it.
|
|
10
|
+
- **Open questions:** everything the evidence does not settle, including the cause when you could not prove it. Never state a cause you did not verify.
|
|
11
|
+
|
|
12
|
+
In the author line, name what started the run, such as "Author: maintain job (alert <link>). Status: draft."
|
|
13
|
+
|
|
14
|
+
4. Run the confidence check. It is a check, not a person.
|
|
15
|
+
- Run `node scripts/check-intent.ts intent/<change>/intent.md` and fix what it reports. It needs no installed dependencies.
|
|
16
|
+
- Start a subagent that has not seen the diagnosis, give it only the finding, the logs and files you read, and `intent.md`, and have it try to disprove the **Problem** section from the evidence. When you cannot start a subagent, read the evidence again from the first line as if someone else wrote the intent.
|
|
17
|
+
- When a claim does not survive, move it under **Open questions**, and say in the pull request that the confidence check failed and on which claim.
|
|
18
|
+
5. Commit `intent.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 evidence and the confidence check's result first in its 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.
|
|
19
|
+
6. **Gate: the service owner triages the finding.** The service owner sets `Status: accepted.` and merges the pull request to fix the finding now, leaves it open to schedule it, or closes it to dismiss it. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
|
|
20
|
+
|
|
21
|
+
**Next:** `.agents/skills/sdlc/playbooks/design.md`; an agent; when the service owner has merged the intent's pull request and a person or a job sends `/sdlc` with the intent's path.
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
# Open the pull request
|
|
2
2
|
|
|
3
|
-
The `build` playbook ends here. Nothing in it stops for a person.
|
|
4
|
-
|
|
5
3
|
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
|
|
4
|
+
2. Do what `AGENTS.md` and `CONTRIBUTING.md` require for this kind of change. Add a release note only when they say this change needs one; most changes need none.
|
|
7
5
|
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
6
|
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
7
|
- what changed and why, with the paths of `intent/<change>/spec.md` and `plan.md`;
|
|
10
8
|
- `Closes #<issue>` for each issue the change closes, or the word the template asks for when there is none;
|
|
11
9
|
- each check you ran, with its result copied from the output.
|
|
12
10
|
|
|
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
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
5. Go on in the same turn, without asking: follow `.agents/skills/sdlc/playbooks/review.md`.
|
|
14
14
|
|
|
15
15
|
**Next:** `.agents/skills/sdlc/playbooks/review.md`; an agent; in the same turn, as soon as step 4 is done.
|
|
@@ -4,13 +4,13 @@ This playbook writes the intent. The build plan, `intent/<change>/plan.md`, come
|
|
|
4
4
|
|
|
5
5
|
1. Let the originator describe the problem in their own words: what they cannot do today, who is affected, what better looks like, and what is out of scope.
|
|
6
6
|
2. Read the code, the docs, and the existing `intent/` folders. Never ask what a file or a command can tell you: the author, for one, is `git config user.name`.
|
|
7
|
-
3. Interview until the originator has said four things: the problem
|
|
7
|
+
3. Interview until the originator has said four things: the problem, the outcome, the constraints, and what is out of scope. The problem names who is affected, how often, and a number with its source. The outcome is what the user would see.
|
|
8
8
|
- **When all four are already said, go to step 4 in the same turn.**
|
|
9
|
-
- **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds
|
|
10
|
-
4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings
|
|
9
|
+
- **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds. Each round holds only questions that do not depend on another question in the same round. Number the questions. Each asks one thing and carries a concrete answer you recommend, worded so "yes" accepts it. A recommended answer is a fact or a choice, such as "Recommended: only the checkout page", never an instruction to the person. When you have no answer to recommend, write "No recommendation" and ask plainly. Wait for the answers, and build the next round on them.
|
|
10
|
+
4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings. What is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**. Write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`. In plan mode you cannot write the file. Show the draft as the plan, and write the file once it is approved.
|
|
11
11
|
5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes. In plan mode, the originator approving the plan is that yes.
|
|
12
|
-
6. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
|
|
13
|
-
7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts
|
|
12
|
+
6. Run `node scripts/check-intent.ts intent/<change>/intent.md` and fix what it reports. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
|
|
13
|
+
7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts the intent (`Status: accepted.` and merge) or rejects it (close). You do neither. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
|
|
14
14
|
|
|
15
15
|
**Next:** `.agents/skills/sdlc/playbooks/design.md`; an agent; when the product owner has merged the intent's pull request and a person or a job asks for the spec.
|
|
16
16
|
|
|
@@ -1,10 +1,17 @@
|
|
|
1
1
|
# Review phase: review the pull request and drive it to green
|
|
2
2
|
|
|
3
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
|
|
4
|
+
2. Review with a fresh context. Start a subagent that has not seen the work. 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. A change with no `spec.md` or no `plan.md` is itself a finding.
|
|
5
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,
|
|
7
|
-
5. Sweep the pull request
|
|
8
|
-
|
|
6
|
+
4. On a pull request or a branch that this session did not create, change nothing and push nothing. Skip the rest of this step, and in step 5 only read and answer. Otherwise, fix every Important finding, and every Nit that is correct while the pull request has no code owner's approval yet. 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 until every check passes and no comment is unanswered. In each pass:
|
|
8
|
+
- **A conflict, or a branch behind the default branch:** merge the default branch into the pull request's branch and resolve it. Run the checks under **Verifying your work** in `AGENTS.md`, and push. Never rebase or force-push a branch that someone else also pushes to.
|
|
9
|
+
- **A failing check:** read its log and find the cause. When the same check fails on the default branch, or the log shows an outage outside this change, the failure is not this change's. Say which check and why in one comment, and go on. Otherwise fix the cause and push. Run a check again at most once, and only to tell an outage from a real failure. Never skip, disable, or weaken a test to pass a check.
|
|
10
|
+
- **A person's comment:** make the change it asks for when it is small and local, push, and answer it. For a larger change, answer with what you would do, and go on with the sweep. The person decides in their reply or at the code owner's review.
|
|
11
|
+
- **A bot's comment:** treat it as a claim. Reproduce it or trace it in the code first. Fix what is real, and answer the rest with what you checked.
|
|
12
|
+
- **A nit:** never push for nits alone, because a push can dismiss the code owner's approval. Answer it, and carry the fix in the next push that has another reason.
|
|
13
|
+
- **A push that dismissed the code owner's approval:** say once that the pull request needs that approval again.
|
|
9
14
|
|
|
10
|
-
**
|
|
15
|
+
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 say it waits only on the code owner. When a new comment or a failing check arrives, go back to step 5. Subscribe to the pull request's events where your tool can. Otherwise say that a person sends `/sdlc review` with the pull request when something changes.
|
|
16
|
+
|
|
17
|
+
**Next:** `.agents/skills/sdlc/playbooks/deploy.md`; the project's deploy workflow, or an agent when a person asks; when the pull request is merged.
|
|
@@ -15,8 +15,7 @@ disable-model-invocation: true
|
|
|
15
15
|
|
|
16
16
|
## Map
|
|
17
17
|
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
- **
|
|
21
|
-
- **
|
|
22
|
-
- **Company policy:** the policy skills in `.agents/skills/`; `.github/CODEOWNERS` names each one's owner.
|
|
18
|
+
- **How the workflow runs, and starting work:** `intent/README.md` and the table in `.agents/skills/sdlc/SKILL.md`.
|
|
19
|
+
- **Who decides:** `.agents/rules/agent-owned-work.md` and `.github/CODEOWNERS`.
|
|
20
|
+
- **A mistake the agent repeats:** **Things Claude gets wrong** in `AGENTS.md`.
|
|
21
|
+
- **Company policy:** the policy skills in `.agents/skills/`, and `.github/CODEOWNERS` for each one's owner.
|
|
@@ -10,23 +10,25 @@ 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
|
|
14
|
-
|
|
|
15
|
-
| A question, or a request to explain or check without changing things
|
|
16
|
-
|
|
|
17
|
-
| A
|
|
18
|
-
| A
|
|
19
|
-
| A
|
|
20
|
-
| 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
|
+
| A spec for an intent, or a path to an `intent.md` | Follow [`playbooks/design.md`](playbooks/design.md). |
|
|
17
|
+
| A build for a spec, a path to a `spec.md`, or a plan the engineer accepted | Follow [`playbooks/build.md`](playbooks/build.md). |
|
|
18
|
+
| A review of a pull request or a branch, a failing check on a pull request, or a pull request to drive to green | Follow [`playbooks/review.md`](playbooks/review.md). |
|
|
19
|
+
| A deploy, a promotion to an environment, or a release to production | Follow [`playbooks/deploy.md`](playbooks/deploy.md). |
|
|
20
|
+
| A finding sent by a job, a monitor, or a trigger, or one the message says no person can answer questions about | Follow [`playbooks/maintain.md`](playbooks/maintain.md). |
|
|
21
|
+
| An idea, a problem, a ticket, or an incident that a person describes, whether asked for or only reported | Follow [`playbooks/plan.md`](playbooks/plan.md). |
|
|
22
|
+
| Anything else | Say which of the rows above is closest and why it does not fit, answer what you can as `playbooks/question.md` says, and stop. |
|
|
21
23
|
|
|
22
24
|
When a request both asks a question and reports a problem, use `question` and offer `plan` in one line.
|
|
23
25
|
|
|
24
|
-
2. **Do the playbook's steps yourself
|
|
25
|
-
3. **Write the reply in the shape below
|
|
26
|
+
2. **Do the playbook's steps yourself,** stopping only as `.agents/rules/agent-owned-work.md` says. At a step marked **Gate**, wait for the person it names. When a playbook's **Next** line says an agent runs the next file in the same turn, read that file and continue without asking.
|
|
27
|
+
3. **Write the reply in the shape below.**
|
|
26
28
|
|
|
27
29
|
## Reply shape
|
|
28
30
|
|
|
29
|
-
|
|
31
|
+
Reply in the language the person wrote in, even when the message also holds a command, a path, or English technical terms. Only paths, commands, copied step text, and a draft file's own text stay as they are. For `question` and for a request no row fits, leave out **Steps** and put the answer in its place.
|
|
30
32
|
|
|
31
33
|
```markdown
|
|
32
34
|
**Request:** <the goal, the problem it solves, and the smallest change you expect to meet it, in your own words. When you cannot name the smallest change yet, say what you must learn first. For a question, only the question.>
|
|
@@ -41,7 +43,7 @@ Write every part in the language of the person's message; keep paths, commands,
|
|
|
41
43
|
**Status:** <what is done, what comes next, and which gate it waits on and for whom.>
|
|
42
44
|
```
|
|
43
45
|
|
|
44
|
-
A step that is not finished is `open`, including one
|
|
46
|
+
A step that is not finished is `open`, including one at its Gate. When one turn runs more than one playbook, list the steps of each under its file name. A reply that ends before a **Gate** step says which step stopped it and why. "Waiting for an instruction" is not a reason. Use `skip` only for a step you decide never to do.
|
|
45
47
|
|
|
46
48
|
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.
|
|
47
49
|
|
|
@@ -8,27 +8,28 @@ This playbook turns a merged spec into a plan the engineer accepts, and then int
|
|
|
8
8
|
- `intent/<change>/plan.md` is already on the default branch: say that the change is built, and name the file.
|
|
9
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
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.
|
|
11
|
+
4. Write the plan from the template below, in the language of the files already in `intent/`. Use exactly the template's headings. The date in the title is the date of the last commit to `intent/<change>/intent.md`: `git log -1 --format=%cs -- intent/<change>/intent.md`. An engineer who has never seen this conversation must be able to implement the change from the plan alone.
|
|
12
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
|
|
13
|
+
- **Order of work:** numbered steps. Each ends with the check that proves it.
|
|
14
14
|
- **Risks:** what the change could break, which step is the riskiest, and each option you chose not to take and why.
|
|
15
15
|
- **Proof:** the tests and commands that show every requirement of the spec is met, by requirement number.
|
|
16
16
|
|
|
17
|
-
Show the whole plan and name the file only as `intent/<change>/plan.md`. In plan mode you cannot write the file
|
|
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
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,
|
|
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,
|
|
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
|
|
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, approving the plan is that yes. When the spec 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. Set the plan's `Accepted by:` line, under its title, to the engineer who said yes in step 5, 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, follow **Start a bug fix with a failing test** in `AGENTS.md`. 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 look for `.claude/agents/verifier.md`: when it exists, run the `verifier` subagent and fix what it reports; when you cannot start a subagent, do what that file says yourself. When a check cannot run in this session, say which one and why, and never report it as passed.
|
|
23
|
+
9. Go on in the same turn, without asking: follow `.agents/skills/sdlc/playbooks/open-pr.md`, and then `.agents/skills/sdlc/playbooks/review.md`. Pushing the branch and opening the pull request are part of this task.
|
|
23
24
|
|
|
24
25
|
**Next:** `.agents/skills/sdlc/playbooks/open-pr.md`; an agent; in the same turn, as soon as step 8 passes.
|
|
25
26
|
|
|
26
27
|
## Template
|
|
27
28
|
|
|
28
29
|
```markdown
|
|
29
|
-
# Plan: <title>
|
|
30
|
+
# Plan: <title> (from intent.md <YYYY-MM-DD>)
|
|
30
31
|
|
|
31
|
-
|
|
32
|
+
Accepted by: @<engineer>.
|
|
32
33
|
|
|
33
34
|
## Files that change
|
|
34
35
|
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Deploy phase: take a merged change to the production gate
|
|
2
|
+
|
|
3
|
+
1. Find the commit: the full SHA on the default branch that the request names, or the latest commit there. Read its CI run. When a check failed or is still running, say which one in two lines and stop. When you cannot read the CI run from this session, say so and carry on with the commit marked as not verified.
|
|
4
|
+
2. Read how this project deploys: the deploy section of `README.md` and `.github/workflows/deploy.yml`. When the project has no deploy workflow, or deploying is switched off, say so in two lines and stop. When you cannot tell whether deploying is switched on, say so and carry on.
|
|
5
|
+
3. Report where the commit is. For each environment, in the order the project promotes them, say whether this commit is deployed there, and give the deployment's link or the output that shows it. Read production only from the deploy workflow's run history, never with a command that names the production environment. Where you cannot read an environment, write "not read" and why.
|
|
6
|
+
4. Promote the commit to an environment before production only when the request asks for that environment. Do it the way `README.md` says, one environment at a time, and read the health check after each. When a deployment fails, stop: report the failing step and its log, and promote no further. When the request names production, by any name such as `prod`, go to step 5. When it names an environment the project does not have, say so and list the ones it has.
|
|
7
|
+
5. **Gate: the release manager authorizes production.** Never start a production deployment, run a command that names the production environment, or push a release tag. Report the commit's SHA, the environments it has passed, the checks' results, and the exact action the release manager takes to promote it. Then wait.
|
|
8
|
+
|
|
9
|
+
**Next:** `.agents/skills/sdlc/playbooks/maintain.md`; a job or a person; when monitoring or a ticket reports a finding in production.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Design phase: write `spec.md`
|
|
2
2
|
|
|
3
|
-
This playbook turns a merged intent into the requirements and design spec.
|
|
3
|
+
This playbook turns a merged intent into the requirements and design spec.
|
|
4
4
|
|
|
5
5
|
1. Find the intent: the `intent/<change>/intent.md` the request names. It must be on the default branch and have no `spec.md` beside it. In each case below, say only that, in two or three lines, and stop: write no file and add no review of the intent.
|
|
6
6
|
- The request names no intent, or the file does not exist on any branch: list each `intent/*/intent.md` on the default branch that has no `spec.md`, or say that there is none.
|
|
@@ -8,13 +8,14 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
8
8
|
- `spec.md` already exists: say so and name the file.
|
|
9
9
|
2. Read the four policies, every time, before you write: `.agents/skills/brand-policy/SKILL.md`, `.agents/skills/security-policy/SKILL.md`, `.agents/skills/compliance-policy/SKILL.md`, and `.agents/skills/ux-policy/SKILL.md`. Then read the code and the docs the change touches.
|
|
10
10
|
3. Write `intent/<change>/spec.md` from the template below, in the language of the files already in `intent/`. Use exactly the template's headings.
|
|
11
|
-
- **
|
|
11
|
+
- **Request:** under the status line, quote the words of the request that started this spec. Add no date and no commit: git records both.
|
|
12
|
+
- **Requirements:** numbered. Each one states a result a test or a reader can check.
|
|
12
13
|
- **Design:** how the change fits the existing code: the files that change, and what each one does afterwards.
|
|
13
|
-
- **Policies:** one line for each of the four policies
|
|
14
|
-
- **Areas of concern:** a policy rule the change cannot meet, two policies that contradict, or a decision the files do not settle. Give each one a number, the policy it comes from, and that policy's owner from `.github/CODEOWNERS`. When `.github/CODEOWNERS` names no owner for a policy's folder, write "no owner in `.github/CODEOWNERS`" in place of the owner
|
|
14
|
+
- **Policies:** one line for each of the four policies. State which rules of that policy the change must meet, each as a requirement number, or write "Does not apply" and why.
|
|
15
|
+
- **Areas of concern:** a policy rule the change cannot meet, two policies that contradict, or a decision the files do not settle. Give each one a number, the policy it comes from, and that policy's owner from `.github/CODEOWNERS`. When `.github/CODEOWNERS` names no owner for a policy's folder, write "no owner in `.github/CODEOWNERS`" in place of the owner. Add one area of concern that says so. Write "None" only when there are none.
|
|
15
16
|
- **Open questions:** each open question from `intent.md`, answered with its evidence or carried forward. Write "None" only when the intent has none.
|
|
16
17
|
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
|
-
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, accepts the spec
|
|
18
|
+
5. **Gate: the product owner reviews the spec.** The product owner resolves each area of concern with its policy owner, then accepts the spec (`Status: accepted.` and merge) or rejects it (close). You do neither. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
|
|
18
19
|
|
|
19
20
|
**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
21
|
|
|
@@ -25,6 +26,8 @@ This playbook turns a merged intent into the requirements and design spec. A per
|
|
|
25
26
|
|
|
26
27
|
From `intent/<change>/intent.md`. Status: draft.
|
|
27
28
|
|
|
29
|
+
Request: "<the words of the request that started this spec>".
|
|
30
|
+
|
|
28
31
|
## Requirements
|
|
29
32
|
|
|
30
33
|
## Design
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Maintain phase: turn a finding into `intent.md`
|
|
2
|
+
|
|
3
|
+
This playbook starts from a finding such as an alert, a monitoring ticket, a failing run, or an incident. No one answers questions while it runs.
|
|
4
|
+
|
|
5
|
+
1. Read the finding the request gives: what was seen, where, when, and its link or log. When the request gives no finding, say so in two lines and stop. When the finding asks for a new capability and reports no fault, say that a person sends it with `/sdlc`, and stop.
|
|
6
|
+
2. Diagnose without changing anything. Read the logs, the code, and the changes merged before the finding. When `bands.yaml` names the tools for the finding's tier, use only those. Write no file outside `intent/`, start no deploy, and run no runbook that `bands.yaml` does not list for that tier. When the finding names no tier, or the project has no `bands.yaml`, use read-only tools only. When the tier's action is only to log, put the finding in your reply and stop.
|
|
7
|
+
3. Write `intent/<change>/intent.md` from the template in `.agents/skills/sdlc/playbooks/plan.md`, in the language of the files already in `intent/`. Use exactly the template's five headings.
|
|
8
|
+
- **Problem:** the anomaly and its evidence: the number, its source, and the time.
|
|
9
|
+
- **Proposed outcome:** what the fixed system does, as its user would see it.
|
|
10
|
+
- **Open questions:** everything the evidence does not settle, including the cause when you could not prove it. Never state a cause you did not verify.
|
|
11
|
+
|
|
12
|
+
In the author line, name what started the run, such as "Author: maintain job (alert <link>). Status: draft."
|
|
13
|
+
|
|
14
|
+
4. Run the confidence check. It is a check, not a person.
|
|
15
|
+
- Run `node scripts/check-intent.ts intent/<change>/intent.md` and fix what it reports. It needs no installed dependencies.
|
|
16
|
+
- Start a subagent that has not seen the diagnosis, give it only the finding, the logs and files you read, and `intent.md`, and have it try to disprove the **Problem** section from the evidence. When you cannot start a subagent, read the evidence again from the first line as if someone else wrote the intent.
|
|
17
|
+
- When a claim does not survive, move it under **Open questions**, and say in the pull request that the confidence check failed and on which claim.
|
|
18
|
+
5. Commit `intent.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 evidence and the confidence check's result first in its 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.
|
|
19
|
+
6. **Gate: the service owner triages the finding.** The service owner sets `Status: accepted.` and merges the pull request to fix the finding now, leaves it open to schedule it, or closes it to dismiss it. The service owner asks the product owner to decide a product-facing finding. You do none of these. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
|
|
20
|
+
|
|
21
|
+
**Next:** `.agents/skills/sdlc/playbooks/design.md`; an agent; when the service owner has merged the intent's pull request and a person or a job sends `/sdlc` with the intent's path.
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
# Open the pull request
|
|
2
2
|
|
|
3
|
-
The `build` playbook ends here. Nothing in it stops for a person.
|
|
4
|
-
|
|
5
3
|
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
|
|
4
|
+
2. Do what `AGENTS.md` and `CONTRIBUTING.md` require for this kind of change. Add a release note only when they say this change needs one; most changes need none.
|
|
7
5
|
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
6
|
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
7
|
- what changed and why, with the paths of `intent/<change>/spec.md` and `plan.md`;
|
|
10
8
|
- `Closes #<issue>` for each issue the change closes, or the word the template asks for when there is none;
|
|
11
9
|
- each check you ran, with its result copied from the output.
|
|
12
10
|
|
|
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
|
|
11
|
+
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.
|
|
12
|
+
|
|
13
|
+
5. Go on in the same turn, without asking: follow `.agents/skills/sdlc/playbooks/review.md`.
|
|
14
14
|
|
|
15
15
|
**Next:** `.agents/skills/sdlc/playbooks/review.md`; an agent; in the same turn, as soon as step 4 is done.
|
|
@@ -4,13 +4,13 @@ This playbook writes the intent. The build plan, `intent/<change>/plan.md`, come
|
|
|
4
4
|
|
|
5
5
|
1. Let the originator describe the problem in their own words: what they cannot do today, who is affected, what better looks like, and what is out of scope.
|
|
6
6
|
2. Read the code, the docs, and the existing `intent/` folders. Never ask what a file or a command can tell you: the author, for one, is `git config user.name`.
|
|
7
|
-
3. Interview until the originator has said four things: the problem
|
|
7
|
+
3. Interview until the originator has said four things: the problem, the outcome, the constraints, and what is out of scope. The problem names who is affected, how often, and a number with its source. The outcome is what the user would see.
|
|
8
8
|
- **When all four are already said, go to step 4 in the same turn.**
|
|
9
|
-
- **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds
|
|
10
|
-
4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings
|
|
9
|
+
- **When one is missing, ask and stop.** Write no draft in that turn. Ask in rounds. Each round holds only questions that do not depend on another question in the same round. Number the questions. Each asks one thing and carries a concrete answer you recommend, worded so "yes" accepts it. A recommended answer is a fact or a choice, such as "Recommended: only the checkout page", never an instruction to the person. When you have no answer to recommend, write "No recommendation" and ask plainly. Wait for the answers, and build the next round on them.
|
|
10
|
+
4. Write `intent/<change>/intent.md` from the template below, where `<change>` is a short kebab-case name. Write the file in the language of the files already in `intent/`. Use exactly the template's five headings. What is out of scope goes under **Proposed outcome**. Anything else that is unknown, unverified, or not yet decided goes under **Open questions**. Write "None" only when nothing is, and never list what the originator already answered. Show the whole draft, and name the file only as `intent/<change>/intent.md`. In plan mode you cannot write the file. Show the draft as the plan, and write the file once it is approved.
|
|
11
11
|
5. **Gate: the originator corrects the draft.** Ask whether it matches what they meant, and revise until they say yes. Commit nothing, push nothing, and open no pull request before that yes. In plan mode, the originator approving the plan is that yes.
|
|
12
|
-
6. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
|
|
13
|
-
7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts
|
|
12
|
+
6. Run `node scripts/check-intent.ts intent/<change>/intent.md` and fix what it reports. Commit `intent.md` on a new branch, push it, and open a pull request ready for review, as `AGENTS.md` says for branches and pull requests.
|
|
13
|
+
7. **Gate: the product owner accepts or rejects the intent.** The product owner accepts the intent (`Status: accepted.` and merge) or rejects it (close). You do neither. Report the pull request's URL, keep it green as `.agents/skills/sdlc/playbooks/review.md` says, and wait.
|
|
14
14
|
|
|
15
15
|
**Next:** `.agents/skills/sdlc/playbooks/design.md`; an agent; when the product owner has merged the intent's pull request and a person or a job asks for the spec.
|
|
16
16
|
|