Skip to content

Commit 8cbf778

Browse files
authored
Merge AGENTS prompt, propagate agent rules and implicit phrs behavior pull request github#15 from panaversity/chore/consolidate-agents-system-prompt
2 parents 1003c26 + aea19c7 commit 8cbf778

10 files changed

Lines changed: 406 additions & 126 deletions

File tree

‎AGENTS.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,80 @@ The toolkit supports multiple AI coding assistants, allowing teams to use their
1414

1515
- Any changes to `__init__.py` for the Specify CLI require a version rev in `pyproject.toml` and addition of entries to `CHANGELOG.md`.
1616

17+
### Prompt Evaluation Flywheel (Analyze → Measure → Improve)
18+
19+
Apply this loop whenever writing or refining prompts, specs, or command templates:
20+
21+
1) Analyze: list likely failure modes and translate them into binary pass/fail oracles.
22+
2) Measure: create a few strict binary graders (formatting, requirements, safety) with few‑shot PASS/FAIL examples; keep examples in PHRs or `eval/`.
23+
3) Improve: when a grader FAILs, adjust the smallest part of the prompt to address that failure; re‑run graders until PASS.
24+
25+
This complements TDD and ADRs—tests verify behavior; graders verify prompt structure and clarity; ADRs preserve consequential reasoning.
26+
27+
### System Instructions (Prompt Structure)
28+
29+
Adopt this 10‑part structure (inspired by Anthropic’s guidance) when writing prompts/specs:
30+
31+
1. Task context – one‑sentence goal, surface (spec/plan/tasks/code), success criteria
32+
2. Tone context – professional, concise, constructive
33+
3. Background data – files/PRDs/screens; cite with code references
34+
4. Detailed task description & rules – constraints, non‑goals, invariants; never invent APIs; no secrets; prefer minimal diffs
35+
5. Examples – minimal happy‑path + edge example
36+
6. Conversation history – 1–3 bullets of prior decisions; link PHR
37+
7. Immediate request – what to produce now with acceptance criteria
38+
8. Think step by step – reasoning is private; output decisions and results only
39+
9. Output formatting – diffs, lists, checkboxes; cite existing code with code references (start:end:path)
40+
10. Prefilled response (if any) – skeletons to fill
41+
42+
Tie‑ins:
43+
- After output, create a PHR (implicit). Feature branches add `specs/<feature>/prompts/`.
44+
- If decision significance test passes, show ADR suggestion text and wait for consent.
45+
46+
Minimum acceptance criteria for any prompt output
47+
- Clear, testable acceptance criteria included
48+
- Explicit error paths and constraints stated
49+
- Smallest viable change; no unrelated edits
50+
- Code references to modified/inspected files where relevant
51+
52+
### Default policies (must follow)
53+
- Do not invent APIs, data, or contracts; ask targeted clarifiers if missing.
54+
- Never hardcode secrets or tokens; use `.env` and docs.
55+
- Prefer the smallest viable diff; do not refactor unrelated code.
56+
- Cite existing code with code references; propose new code in fenced blocks.
57+
- Keep reasoning private; output only decisions, artifacts, and justifications.
58+
59+
### Execution contract for every request
60+
1) Confirm surface and success criteria (one sentence).
61+
2) List constraints, invariants, non‑goals.
62+
3) Produce the artifact with acceptance checks inlined (checkboxes or tests where applicable).
63+
4) Add follow‑ups and risks (max 3 bullets).
64+
5) Trigger implicit PHR; if plan/tasks identified decisions that meet significance, surface ADR suggestion text.
65+
66+
### Compact grader template (copy/paste)
67+
Use this to create binary evaluators for outputs.
68+
69+
```
70+
You are a strict PASS/FAIL grader.
71+
Task: Judge whether the candidate output satisfies the criteria.
72+
If ALL criteria are satisfied → PASS, else → FAIL and list violated items.
73+
74+
Criteria:
75+
- {criterion 1}
76+
- {criterion 2}
77+
- {criterion 3}
78+
79+
Few‑shot examples:
80+
PASS:
81+
- Input: {short}
82+
- Output: {short}
83+
- Rationale: All criteria satisfied.
84+
85+
FAIL:
86+
- Input: {short}
87+
- Output: {short}
88+
- Rationale: Violates {criterion}.
89+
```
90+
1791
## Adding New Agent Support
1892

1993
This section explains how to add support for new AI agents/assistants to the Specify CLI. Use this guide as a reference when integrating new AI tools into the Spec-Driven Development workflow.

‎memory/command-rules.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1-
After completing the main command, automatically create a PHR: (1) Detect stage: constitution|spec|architect|green|red|refactor|explainer|general, (2) Generate 3-7 word title, (3) Load `.**/commands/sp.phr.md` and execute with $ARGUMENTS (FULL multiline input, NOT truncated), detected stage, implicit mode, (4) On error: warn but don't block. CRITICAL: Preserve complete user input in PHR. Skip only for /sp.phr itself.
1+
As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
22

3-
**Architecture Decisions**: When significant architectural decisions are made (typically during /sp.plan), suggest documenting with: "📋 Architecture decisions identified. Document reasoning and tradeoffs? Run `/sp.adr [decision-title]`" Wait for user consent.
3+
1) Determine Stage
4+
- Stage: constitution | spec | plan | tasks | implementation | debugging | refactoring | discussion | general
5+
6+
2) Generate Title and Decide Prompt Path:
7+
- Generate Title: 3–7 words (slug for filename)
8+
- If feature context is detected (explicit marker, branch name, or touched `specs/<name>/`), target `specs/<name>/prompts/`; else target `docs/prompts/`.
9+
10+
3) Create and Fill PHR (Shell first; fallback agent‑native)
11+
- Use the route from step 2 (docs vs specs) as the target directory.
12+
- Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> --json`
13+
- If the created file is not under the routed target, MOVE it to that folder and update `feature`/`branch` in the front‑matter.
14+
- Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
15+
- If the script fails:
16+
- Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
17+
- Allocate an ID; compute the output path from step 2; write the file
18+
- Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
19+
20+
5) Validate + report
21+
- No unresolved placeholders; path matches route; stage/title/date coherent; print ID + path + stage + title.
22+
- On failure: warn, don’t block. Skip only for `/sp.phr`.

0 commit comments

Comments
 (0)