diff --git a/codev/.update-hashes.json b/codev/.update-hashes.json new file mode 100644 index 0000000..e5aac26 --- /dev/null +++ b/codev/.update-hashes.json @@ -0,0 +1,87 @@ +{ + "protocols/air/builder-prompt.md": "b2acd782a02f1b4426ab50c3628b35340655e9a9b733e667ca655cf171c95931", + "protocols/air/consult-types/impl-review.md": "06001891a3e2df5722b96802f46d2c6563c8006fdfa795d41f9eb629b824d949", + "protocols/air/consult-types/pr-review.md": "e844a116f32fa55667ca331f906a46c70d40c2b55d3ac1fb64dad112a438b371", + "protocols/air/prompts/implement.md": "b891b33a37ff4b1801a62bc93f4a5835c0486bebeed072287905c4c5f7e7adfd", + "protocols/air/prompts/pr.md": "ef459a6bb82e27eb264a12c2f1212baacde0e753196a5e8e6e14c2a95af5cffc", + "protocols/air/protocol.json": "92eec229f4406a27bab90a316c21b14b15b46b530550c4c92e043ce1c2ba8bed", + "protocols/air/protocol.md": "621b7ef44d51a1c45ae1cd2a0531be607c37978e03e4c4c3dcdc0bbcf315efa4", + "protocols/aspir/builder-prompt.md": "ed30dce2c4e3b38a3ecfdf6ffe3ec1faf103cfca7cdc95da29589317db36d699", + "protocols/aspir/consult-types/impl-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/aspir/consult-types/phase-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/aspir/consult-types/plan-review.md": "adaea07d98ad33d257898c291dce3d8fda9d1cab3ccdd7bb47ad6d2d8dfa5137", + "protocols/aspir/consult-types/pr-review.md": "1f63abdf64bf5e915cf5979f7bf772b2701f7ff6eaaebadfe5beebe1bebfec83", + "protocols/aspir/consult-types/spec-review.md": "71b29b32f5d8a99b490edf459aa971b94bfd2c6fa312b5166c2d31b22e7463f2", + "protocols/aspir/prompts/implement.md": "2d5f5d57ed9b45d0e0242046d7db4b914a4d96eab20b1f46d48bb807db0edf5e", + "protocols/aspir/prompts/plan.md": "1a62634a82d0ddca56af1225c3f28635c89ce847c199a85973d1037df2e85b0c", + "protocols/aspir/prompts/review.md": "e67f945ad24e04560a3b0f364c14f8042e91554bf8d086e84fc00acce3df1dca", + "protocols/aspir/prompts/specify.md": "5c6914c126c637785a2c70d02fc69bb4876169b98494492d1a78184cefc87262", + "protocols/aspir/protocol.json": "cb3831d6f0e82f7ab6324e07ea1d12780e51ec56d77950346fc1c4cbd57f7e11", + "protocols/aspir/protocol.md": "2ac5f208e70d2350276d01d0c5e86eb5e443bb9e519ac94bb725fd08c717d752", + "protocols/aspir/templates/plan.md": "590748f5a8d2e75e996fa55b3ac2594a0320f7a8783d218c64e0f1265a70c54f", + "protocols/aspir/templates/review.md": "47183b106acd750f9e7e33bc03d0821e60ad7b0543c404b3e484ebe1c4b26cc0", + "protocols/aspir/templates/spec.md": "5d285bf27a090667b38031fa7fdd3d50c6912f522fe6b0c98fe464024dc1be2d", + "protocols/bugfix/builder-prompt.md": "554ff2b3f7e278f78e73c924c3925c31eeb913f404743b94836a1955501e5cff", + "protocols/bugfix/consult-types/impl-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/bugfix/consult-types/pr-review.md": "1f63abdf64bf5e915cf5979f7bf772b2701f7ff6eaaebadfe5beebe1bebfec83", + "protocols/bugfix/prompts/fix.md": "8f064391a0fecf1a9993d575cf958074e17f5a002110e669262d86bf6480b3ea", + "protocols/bugfix/prompts/investigate.md": "ea4a357896e681dd7331752bfb92e3f1430b43b6ed805d26c5832ea2d4f511ef", + "protocols/bugfix/prompts/pr.md": "eccfa486ccf8d2bd5aa47ff32684512ce19ccb22e94c269a536b09939bc87bcd", + "protocols/bugfix/protocol.json": "c7306fde4c84688675a340227435812fd2d0a6fc8a6797b8b61cb03426e52db9", + "protocols/experiment/builder-prompt.md": "f2e0dd7b5ab59dc9e6b14aee2188661a4e59c8fc5f4fee633bbe1282d7efd2c1", + "protocols/experiment/protocol.json": "93f4461dee32f1427f8d0343675e78be10f393ff91fffa818fa9df591316f4dc", + "protocols/experiment/protocol.md": "0b16e4567c7128568f78fd270657755daf90cd6e4869dc3360364aa84e1d1521", + "protocols/experiment/templates/notes.md": "d7b49794a07db3c8175c29c9baf76973416f2a9d9ec133c7429fc37a067dd0d6", + "protocols/maintain/builder-prompt.md": "85b33d21d1522373efe41081c7e76d66f6ddf01f95f24d36c4cfeae0ae6e65ec", + "protocols/maintain/consult-types/impl-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/maintain/consult-types/pr-review.md": "1f63abdf64bf5e915cf5979f7bf772b2701f7ff6eaaebadfe5beebe1bebfec83", + "protocols/maintain/prompts/audit.md": "5a7ffea829dbc27a3f433de12fbd1c5b7902a8a945bf17868aea732aa75f0c8b", + "protocols/maintain/prompts/clean.md": "30061cf0eb7bec533e893f3148b6563e6b7b4c38f9dbd93c1be72542aa047059", + "protocols/maintain/prompts/sync.md": "3ddfbd5e1d5ae9b89cf5d91968b2353d76a5f743b6d7b8a66f3a54632e0d7f8a", + "protocols/maintain/prompts/verify.md": "1fb8b8ba3a1772d2d07d843f5c601bfef60d007aa72108cc6e83f8524e62df4d", + "protocols/maintain/protocol.json": "4bb736b1f2f295166dd9a58a973cd5dec6b76b3b2ca490b54f946c0d0efbf096", + "protocols/maintain/protocol.md": "09dbc868eca24a5e4f5705ead72f5d20937c714b8c9101f5710d3240bd5cabc5", + "protocols/maintain/templates/maintenance-run.md": "6bbd4a11f946a610e5bcccf0ca90e6064ec1776eedccb07bc6885a334a76ac08", + "protocols/protocol-schema.json": "02cd6945c385443e0c6673cc64a052804eed597e22301a5779c54c6755de1eda", + "protocols/spike/builder-prompt.md": "a389f269b8eb53b4f978e55c819e05165c3f343a5bccba868bcd3d4334e911a5", + "protocols/spike/protocol.json": "f6948f3e5159fbabbe2cfc869a9d910f9e20b4638c3828225f065f5ee36cc858", + "protocols/spike/protocol.md": "d24848da55501e06d7e737e8e2da87b7d0f43d4ee326c3e8f175e2357d937362", + "protocols/spike/templates/findings.md": "ce2d0c2586eefbab8738ae7844f0e75e2aa2aec0dea78e32932867b2240aa867", + "protocols/spir/builder-prompt.md": "ed30dce2c4e3b38a3ecfdf6ffe3ec1faf103cfca7cdc95da29589317db36d699", + "protocols/spir/consult-types/impl-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/spir/consult-types/phase-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/spir/consult-types/plan-review.md": "adaea07d98ad33d257898c291dce3d8fda9d1cab3ccdd7bb47ad6d2d8dfa5137", + "protocols/spir/consult-types/pr-review.md": "1f63abdf64bf5e915cf5979f7bf772b2701f7ff6eaaebadfe5beebe1bebfec83", + "protocols/spir/consult-types/spec-review.md": "71b29b32f5d8a99b490edf459aa971b94bfd2c6fa312b5166c2d31b22e7463f2", + "protocols/spir/prompts/implement.md": "2d5f5d57ed9b45d0e0242046d7db4b914a4d96eab20b1f46d48bb807db0edf5e", + "protocols/spir/prompts/plan.md": "1a62634a82d0ddca56af1225c3f28635c89ce847c199a85973d1037df2e85b0c", + "protocols/spir/prompts/review.md": "e67f945ad24e04560a3b0f364c14f8042e91554bf8d086e84fc00acce3df1dca", + "protocols/spir/prompts/specify.md": "5c6914c126c637785a2c70d02fc69bb4876169b98494492d1a78184cefc87262", + "protocols/spir/protocol.json": "61193d795dad74af0b42452df1607fbc6fc1ea81a9af2cc968b4440320c70d0c", + "protocols/spir/protocol.md": "f9297b94ff2a296f45329a72c1f8bc08d817ec5b7055392ff0120bd9191788e5", + "protocols/spir/templates/plan.md": "590748f5a8d2e75e996fa55b3ac2594a0320f7a8783d218c64e0f1265a70c54f", + "protocols/spir/templates/review.md": "47183b106acd750f9e7e33bc03d0821e60ad7b0543c404b3e484ebe1c4b26cc0", + "protocols/spir/templates/spec.md": "5d285bf27a090667b38031fa7fdd3d50c6912f522fe6b0c98fe464024dc1be2d", + "protocols/tick/builder-prompt.md": "bb4d5eab37b786cf8db9f91698d11486ca4f595950bf9b93cbd20000202e9e13", + "protocols/tick/consult-types/impl-review.md": "e23d51f2027d0b1492c5db7350dd0cade6d60e9c51617b4a87f8ec9f152e195a", + "protocols/tick/consult-types/plan-review.md": "adaea07d98ad33d257898c291dce3d8fda9d1cab3ccdd7bb47ad6d2d8dfa5137", + "protocols/tick/consult-types/pr-review.md": "1f63abdf64bf5e915cf5979f7bf772b2701f7ff6eaaebadfe5beebe1bebfec83", + "protocols/tick/consult-types/spec-review.md": "71b29b32f5d8a99b490edf459aa971b94bfd2c6fa312b5166c2d31b22e7463f2", + "protocols/tick/protocol.json": "e124dba1fb2918868c34c5bd5475857f7be1e7bf0d2fef2f133ad85dd37428a1", + "protocols/tick/protocol.md": "412cd5e9600e988ebe5a4338c902bbb8c43b3322ea2cc7e54054f0fea2f534bc", + "protocols/tick/templates/plan.md": "74a8810b696b49b8c38bbaa75ceb35ff33494feb6cab6058a873c5406ef0987c", + "protocols/tick/templates/review.md": "9a19816fef965a22e88f29935dd3c0ae5f21a9d603820bfbd08b4ea25f0fc2c1", + "protocols/tick/templates/spec.md": "6dc83459a4ee6973e25be638303e3bfcce54556661577d18884913c86ddc4021", + "resources/commands/agent-farm.md": "e31be4eddfcdbe7a33dd383fd7d76397c3950a63be829facb0d8d69e12141b23", + "resources/commands/codev.md": "4199872530cfe6d2d7b99f2c82239f35167fbc36c2c2e0f30827277466688546", + "resources/commands/consult.md": "5c19efc3d6cff82ee0973b1850645d9f057d7bad601848917325abf6f41aba61", + "resources/commands/overview.md": "4847485250a4b17e963a1fee38d93f44bc79a3cd09f1fe07937959ac4bf1000b", + "resources/workflow-reference.md": "5dda6d73f7dfcdb6daa779ccd14c3fda2e6f5bd6678c00bd9adbe4baf30f2ff1", + "templates/AGENTS.md": "47b2371af786292e7f581d78741f0065af43a4c7e8995df1573dbe6b3a89e82d", + "templates/CLAUDE.md": "af0cdfffab08f15d3d27e09a9a44bde2ce4a334f45c38e6ee04dd699f6b6336e", + "templates/arch.md": "6a265de043e003c422532514cddc148a36d928937664ffa66c61f728b20797a5", + "templates/cheatsheet.md": "b92846ad5fc2e4adcd610c96e6281ccc95ae1a7ecf5074aaa5f764a8ee5128a9", + "templates/lessons-learned.md": "b79fbacd47d76ebe393909990eb38d5583e8e928e8218bbcf01cf2882105cac5", + "templates/lifecycle.md": "b4f4ad8dfc40c25a5c33f5797e5958cfce2510bc8d3d7a43b86e825ee5351a6a", + "templates/pr-overview.md": "9884057783064910503dfa8c697142c6d241cce2b7aa860ded5822c46530691f" +} \ No newline at end of file diff --git a/codev/consult-types/integration-review.md b/codev/consult-types/integration-review.md new file mode 100644 index 0000000..d522de2 --- /dev/null +++ b/codev/consult-types/integration-review.md @@ -0,0 +1,75 @@ +# Integration Review Prompt + +## Context +You are performing an integration review of a pull request. The builder has created a PR and you are evaluating whether this change fits well into the broader system. This is the architect's review, focusing on how the change integrates rather than whether it works. + +## Focus Areas + +1. **Architectural Fit** + - Does this change follow existing patterns in the codebase? + - Are there inconsistencies with how similar things are done elsewhere? + - Does it introduce new patterns that should be adopted more broadly? + - Are dependencies appropriate and minimal? + +2. **System Impact** + - What other parts of the system might be affected? + - Are there potential side effects not addressed? + - Does this break any existing functionality? + - Are there performance implications? + +3. **API/Interface Quality** + - Are new interfaces well-designed and consistent? + - Will this be easy for other developers to use? + - Is it properly documented for consumers? + - Does it follow existing conventions? + +4. **Maintenance Burden** + - Is this code maintainable by others? + - Are there any "clever" solutions that should be simplified? + - Is the complexity justified? + - Will this be easy to debug when issues arise? + +5. **Migration/Compatibility** + - Are there backward compatibility concerns? + - Is migration path clear for existing users? + - Are breaking changes properly communicated? + +6. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - Compare spec's "Goals" section and flow diagrams to actual behavior + - If spec says "async/non-blocking", verify the code is actually async + - If spec says "immediate response", verify user isn't blocked waiting + - **CRITICAL:** Tests passing does NOT mean UX requirements are met - verify manually + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... + +INTEGRATION_NOTES: +- [Note about system integration] +- [Note about follow-up work needed] +``` + +**Verdict meanings:** +- `APPROVE`: Ready to merge +- `REQUEST_CHANGES`: Integration issues that must be addressed +- `COMMENT`: Suggestions for improvement, can merge but consider feedback + +## Notes + +- The implementation has already been reviewed - don't re-review code quality +- Focus on "how does this fit the system" not "does this work" +- Consider: Will I regret merging this in 6 months? +- If requesting changes, be specific about what needs to change +- INTEGRATION_NOTES can include suggestions for follow-up specs diff --git a/codev/plans/14-tick-001-jj-auto-install.md b/codev/plans/14-tick-001-jj-auto-install.md new file mode 100644 index 0000000..4ebbd1d --- /dev/null +++ b/codev/plans/14-tick-001-jj-auto-install.md @@ -0,0 +1,99 @@ +# Plan: TICK 14-001 — JJ Auto-Install CLI Command + +## Phase 1: `install-jj` subcommand + +### Files to create/modify + +**`src/fava_trails/cli.py`** — Add `cmd_install_jj` function and wire up subparser: + +```python +def cmd_install_jj(args: argparse.Namespace) -> int: + """Download and install the JJ binary.""" +``` + +Logic: +1. Check if JJ already installed: + - Parse installed version from `jj version` output + - If installed version == target version → print version, exit 0 + - If versions differ → proceed with install (upgrade/downgrade) +2. Detect platform: `sys.platform` + `platform.machine()` +3. Map to release artifact name: + - `linux` + `x86_64` → `x86_64-unknown-linux-musl` + - `linux` + `aarch64` → `aarch64-unknown-linux-musl` + - `darwin` + `x86_64` → `x86_64-apple-darwin` + - `darwin` + `arm64` → `aarch64-apple-darwin` + - `win32` → print `winget install Jujutsu.Jujutsu` and exit 1 + - else → error with manual install URL +4. Download tarball from `https://github.com/jj-vcs/jj/releases/download/v{VERSION}/jj-v{VERSION}-{suffix}.tar.gz` +5. Extract to tempdir, copy `jj` binary to `~/.local/bin/jj` +6. `chmod +x` +7. Verify: run `jj version`, print output +8. Post-install PATH check: run `shutil.which("jj")` — if None, print clear warning with instructions to add `~/.local/bin` to PATH + +Constants: `JJ_VERSION = "0.28.0"` (match `scripts/install-jj.sh`), `INSTALL_DIR = ~/.local/bin` + +Dependencies: `urllib.request`, `tarfile`, `tempfile`, `shutil`, `platform` — all stdlib. + +### Subparser registration + +```python +p_install_jj = subparsers.add_parser("install-jj", help="Download and install the Jujutsu (JJ) binary") +p_install_jj.add_argument("--version", default=None, help="JJ version to install (default: 0.28.0)") +p_install_jj.set_defaults(func=cmd_install_jj) +``` + +### Done criteria +- `fava-trails install-jj` downloads and installs JJ on Linux x86_64 +- Skips if already installed +- `--version` flag allows pinning + +## Phase 2: Error message cleanup + +### Files to modify + +1. **`src/fava_trails/cli.py:212`** (`cmd_bootstrap`): + ``` + - "Error: jj not found. Install with: bash scripts/install-jj.sh" + + "Error: jj not found. Install with: fava-trails install-jj\n Or manually: https://jj-vcs.github.io/jj/" + ``` + +2. **`src/fava_trails/cli.py:427`** (`cmd_doctor`): + ``` + - " Fix: bash scripts/install-jj.sh" + + " Fix: fava-trails install-jj" + ``` + +3. **`src/fava_trails/vcs/jj_backend.py:64-65`** (`_find_jj`): + ``` + - "jj binary not found. Install from https://jj-vcs.github.io/jj/ or run scripts/install-jj.sh (from source repo)" + + "jj binary not found. Install with: fava-trails install-jj (or manually from https://jj-vcs.github.io/jj/)" + ``` + +4. **`tests/conftest.py:14`**: + ``` + - "jj binary not found — install via scripts/install-jj.sh" + + "jj binary not found — install via: fava-trails install-jj" + ``` + +### Done criteria +- Zero references to `scripts/install-jj.sh` in Python source files +- All JJ-missing errors point to `fava-trails install-jj` + +## Phase 3: Tests + +### New tests in `tests/test_cli.py` + +1. `test_install_jj_skips_if_present` — mock `shutil.which` returning jj → exit 0, prints version +2. `test_install_jj_unsupported_platform` — mock `sys.platform` to `"win32"` → exit 1, prints manual URL +3. `test_install_jj_downloads_and_installs` — mock `urllib.request.urlopen`, verify binary placed in expected path +4. `test_install_jj_custom_version` — verify `--version 0.29.0` changes download URL + +### Existing test updates + +- `test_bootstrap_fails_if_jj_missing` — assert new error message text +- `test_cli.py:477` — assert `install-jj` in output (not `install-jj.sh`) +- `test_doctor_jj_missing` — assert new fix message + +### Done criteria +- All new tests pass +- All existing tests pass (181 total) diff --git a/codev/protocols/air/builder-prompt.md b/codev/protocols/air/builder-prompt.md new file mode 100644 index 0000000..bb7ad75 --- /dev/null +++ b/codev/protocols/air/builder-prompt.md @@ -0,0 +1,69 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the AIR protocol yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Consultation is optional — use your judgement based on complexity +- You have flexibility in execution, but must stay compliant with the protocol +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +{{/if}} + +## Protocol +Follow the AIR protocol: `codev/protocols/air/protocol.md` + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} + +## Your Mission +1. Read the issue requirements carefully +2. Implement the feature (< 300 LOC) +3. Write tests for the feature +4. Create PR with review in the PR body (NOT as a separate file) +5. Notify architect via `af send architect "PR #N ready for review (implements #{{issue.number}})"` + +**IMPORTANT**: AIR produces NO spec, plan, or review files. The review goes in the PR body. + +If the feature is too complex (> 300 LOC or architectural changes), notify the Architect via: +```bash +af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to ASPIR." +``` + +## Notifications +Always use `af send architect "..."` to notify the architect at key moments: +- **PR ready**: `af send architect "PR #N ready for review (implements #{{issue.number}})"` +- **PR merged**: `af send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."` +- **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"` +{{/if}} + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in the PR body under a "Flaky Tests" section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the AIR protocol +2. Review the issue details +3. Implement the feature diff --git a/codev/protocols/air/consult-types/impl-review.md b/codev/protocols/air/consult-types/impl-review.md new file mode 100644 index 0000000..aacdefb --- /dev/null +++ b/codev/protocols/air/consult-types/impl-review.md @@ -0,0 +1,58 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work for a small feature built under the AIR protocol. The builder implemented directly from a GitHub issue — there is no spec or plan document. Your job is to verify the implementation matches the issue requirements and follows good practices. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files + +## Focus Areas + +1. **Issue Adherence** + - Does the implementation fulfill the issue requirements? + - Are the described acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate? + - Do tests cover the main paths AND edge cases? + +4. **Scope** + - Is the change under 300 LOC? If not, should this be escalated to ASPIR? + - Does the implementation stay focused on the issue, or does it include unrelated changes? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Implementation looks good, ready for PR +- `REQUEST_CHANGES`: Issues that must be fixed +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Notes + +- AIR has no spec or plan — review against the GitHub issue +- Focus on "does this feature work correctly" not "is this architecturally perfect" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback diff --git a/codev/protocols/air/consult-types/pr-review.md b/codev/protocols/air/consult-types/pr-review.md new file mode 100644 index 0000000..9159039 --- /dev/null +++ b/codev/protocols/air/consult-types/pr-review.md @@ -0,0 +1,58 @@ +# PR Ready Review Prompt + +## Context +You are performing a review of a pull request created under the AIR protocol. The builder implemented a small feature directly from a GitHub issue — there are no spec, plan, or review files. The review is embedded in the PR body. + +## Focus Areas + +1. **Completeness** + - Are the issue requirements implemented? + - Is the PR body review section filled out (summary, key decisions, test plan)? + - Are commits properly formatted? + +2. **Test Status** + - Do all tests pass? + - Is test coverage adequate for the changes? + - Are there any skipped or flaky tests? + +3. **Code Cleanliness** + - Is there any debug code left in? + - Are there any TODO comments that should be resolved? + - Is the code properly formatted? + +4. **Scope** + - Is the change under 300 LOC? + - Does the implementation stay focused on the issue? + - Are there unrelated changes bundled in? + +5. **PR Quality** + - Does the PR link to the issue? + - Is the PR body review section informative? + - Is the branch up to date with main? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Ready for architect review +- `REQUEST_CHANGES`: Issues to fix before review +- `COMMENT`: Minor items, can proceed but note feedback + +## Notes + +- AIR has no spec, plan, or review files — review the PR body and code diff +- Focus on "is this ready for someone else to review" not "is this perfect" +- Any issues found here are cheaper to fix than during integration review diff --git a/codev/protocols/air/prompts/implement.md b/codev/protocols/air/prompts/implement.md new file mode 100644 index 0000000..52767f2 --- /dev/null +++ b/codev/protocols/air/prompts/implement.md @@ -0,0 +1,89 @@ +# IMPLEMENT Phase Prompt + +You are executing the **IMPLEMENT** phase of the AIR protocol. + +## Your Goal + +Read the GitHub issue, implement the feature, and add tests. Keep it focused and under 300 LOC. + +## Context + +- **Issue**: #{{issue.number}} — {{issue.title}} +- **Current State**: {{current_state}} + +## Process + +### 1. Read the Issue + +Read the full issue description. Identify: +- What is the desired behavior? +- What are the acceptance criteria? +- Are there examples or mockups? +- What files/modules are likely affected? + +### 2. Implement the Feature + +Apply a focused implementation: +- Implement what the issue describes — no more, no less +- Do NOT refactor surrounding code +- Do NOT add features beyond what's described in the issue +- Do NOT fix unrelated bugs you happen to notice (file separate issues) + +**Code Quality**: +- Self-documenting code (clear names, obvious structure) +- No commented-out code or debug prints +- Follow existing project conventions + +### 3. Add Tests + +Write tests that: +- Cover the main happy path +- Cover key edge cases +- Are deterministic (not flaky) + +Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.). + +### 4. Verify the Build + +Run build and tests: + +```bash +npm run build # Must pass +npm test # Must pass +``` + +Fix any failures before proceeding. If build/test commands don't exist, check `package.json`. + +### 5. Commit + +Stage and commit your changes: +- Use explicit file paths (never `git add -A` or `git add .`) +- Commit message: `[Air #{{issue.number}}] feat: ` + +## Signals + +When implementation and tests are complete and passing: + +``` +PHASE_COMPLETE +``` + +If the feature is too complex for AIR (> 300 LOC or architectural): + +``` +TOO_COMPLEX +``` + +If you're blocked (missing context, unclear requirements, etc.): + +``` +BLOCKED:reason goes here +``` + +## Important Notes + +1. **Stay focused** — Implement what the issue describes, nothing else +2. **Tests are expected** — Add tests unless the change is purely declarative (e.g., config only) +3. **Build AND tests must pass** — Don't signal complete until both pass +4. **Stay under 300 LOC** — If the feature grows beyond this, signal `TOO_COMPLEX` +5. **No spec/plan artifacts** — AIR does not create files in `codev/specs/` or `codev/plans/` diff --git a/codev/protocols/air/prompts/pr.md b/codev/protocols/air/prompts/pr.md new file mode 100644 index 0000000..e9aae24 --- /dev/null +++ b/codev/protocols/air/prompts/pr.md @@ -0,0 +1,98 @@ +# PR Phase Prompt + +You are executing the **PR** phase of the AIR protocol. + +## Your Goal + +Create a pull request with the review embedded in the PR body, optionally run CMAP, and notify the architect. + +## Context + +- **Issue**: #{{issue.number}} — {{issue.title}} +- **Current State**: {{current_state}} + +## Process + +### 1. Create the Pull Request + +Create a PR that links to the issue. The PR body IS the review — include a summary, key decisions, and test plan: + +```bash +gh pr create --title "[Air #{{issue.number}}] feat: " --body "$(cat <<'EOF' +## Summary + +<1-2 sentence description of the feature> + +Implements #{{issue.number}} + +## What Changed + + + +## Key Decisions + + + +## Test Plan + +- [ ] Unit tests added +- [ ] Build passes +- [ ] All tests pass + +## Review Notes + + +EOF +)" +``` + +**IMPORTANT**: Do NOT create a review file in `codev/reviews/`. The PR body IS the review for AIR. + +### 2. Optional CMAP Review + +If the implementation is non-trivial, run 3-way consultation: + +```bash +consult -m gemini --protocol air --type pr & +consult -m codex --protocol air --type pr & +consult -m claude --protocol air --type pr & +``` + +All three should run in the background (`run_in_background: true`). + +**This is optional** — use your judgement. For simple features (config changes, small UI additions), you may skip consultation. For features touching core logic or multiple modules, run it. + +### 3. Address Feedback (if CMAP was run) + +If you ran CMAP: +- Wait for all consultations to complete +- Record each model's verdict +- Fix any issues identified +- Push updates to the PR branch + +### 4. Notify Architect + +Send notification with PR link: + +```bash +af send architect "PR # ready for review (implements issue #{{issue.number}})" +``` + +If CMAP was run, include verdicts: +```bash +af send architect "PR # ready for review (implements issue #{{issue.number}}). CMAP: gemini=, codex=, claude=" +``` + +## Signals + +When PR is created and ready for review: + +``` +PHASE_COMPLETE +``` + +If you're blocked: + +``` +BLOCKED:reason goes here +``` diff --git a/codev/protocols/air/protocol.json b/codev/protocols/air/protocol.json new file mode 100644 index 0000000..b634eae --- /dev/null +++ b/codev/protocols/air/protocol.json @@ -0,0 +1,109 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "air", + "version": "1.0.0", + "description": "AIR: Autonomous Implement & Review — lightweight protocol for small features from GitHub Issues", + "input": { + "type": "github-issue", + "required": false, + "default_for": ["--issue", "-i"] + }, + "hooks": { + "pre-spawn": { + "collision-check": true, + "comment-on-issue": "On it! Implementing this feature now." + } + }, + "phases": [ + { + "id": "implement", + "name": "Implement", + "description": "Implement the feature and add tests", + "type": "once", + "steps": [ + "read_issue", + "implement_feature", + "add_tests", + "verify_build", + "commit" + ], + "checks": { + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + }, + "tests": { + "command": "npm test -- --exclude='**/e2e/**'", + "description": "Unit tests only - e2e tests run in PR phase", + "on_fail": "retry", + "max_retries": 2 + } + }, + "transition": { + "on_complete": "pr", + "on_too_complex": "escalate" + } + }, + { + "id": "pr", + "name": "Create PR", + "description": "Create pull request with review in PR body", + "type": "once", + "steps": [ + "create_pr", + "link_issue", + "optional_consultation", + "notify_architect" + ], + "consultation": { + "on": "review", + "models": ["gemini", "codex"], + "type": "impl", + "parallel": true, + "max_rounds": 1 + }, + "checks": { + "pr_exists": { + "command": "gh pr list --state all --head \"$(git branch --show-current)\" --json number --jq 'length' | grep -q '^[1-9]'", + "description": "PR must be created before signaling completion" + }, + "e2e_tests": { + "command": "npm run test:e2e 2>&1 || echo 'e2e tests skipped (not configured)'", + "description": "Full e2e test suite", + "optional": true + } + }, + "gate": "pr", + "transition": { + "on_complete": null + } + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current phase is complete", + "transitions_to": "next_phase" + }, + "TOO_COMPLEX": { + "description": "Feature is too complex for AIR, escalate to ASPIR", + "transitions_to": "escalate" + }, + "BLOCKED": { + "description": "Signal implementation is blocked", + "requires": "reason" + } + }, + "defaults": { + "mode": "strict", + "consultation": { + "enabled": true, + "models": ["gemini", "codex"], + "parallel": true + }, + "checks": { + "build": "npm run build", + "test": "npm test" + } + } +} diff --git a/codev/protocols/air/protocol.md b/codev/protocols/air/protocol.md new file mode 100644 index 0000000..deecaba --- /dev/null +++ b/codev/protocols/air/protocol.md @@ -0,0 +1,88 @@ +# AIR Protocol + +> **AIR** = **A**utonomous **I**mplement & **R**eview +> +> A lightweight protocol for small features that are fully specified by their GitHub issue. +> Two phases: Implement → Review. No spec/plan artifacts. + +## What is AIR? + +AIR is a minimal protocol for implementing small features (< 300 LOC) where the GitHub issue provides all the requirements. It skips the Specify and Plan phases entirely — the builder implements directly from the issue and creates a PR with the review embedded in the PR body. + +### How AIR Compares + +| Aspect | BUGFIX | AIR | ASPIR/SPIR | +|--------|--------|-----|------------| +| **Use case** | Bug fixes | Small features | New features | +| **Input** | GitHub Issue | GitHub Issue | GitHub Issue → Spec | +| **Phases** | Investigate → Fix → PR | Implement → PR | Specify → Plan → Implement → Review | +| **Artifacts** | None | None | Spec, plan, review files | +| **Review location** | PR body | PR body | `codev/reviews/` file | +| **Consultation** | PR phase only | Optional (builder decides) | Every phase (3-way) | +| **Human gates** | None (PR gate) | None (PR gate) | Spec + Plan + PR gates (SPIR) | +| **LOC limit** | < 300 | < 300 | No limit | + +### When to Use AIR + +- Small features (< 300 LOC) +- Requirements are clear from the GitHub issue +- No architectural decisions needed +- No new abstractions or significant refactoring required +- Would be overkill for full SPIR/ASPIR ceremony + +### When NOT to Use AIR + +- Bug fixes → use **BUGFIX** +- Features needing spec discussion → use **SPIR** or **ASPIR** +- Amendments to existing specs → use **TICK** +- Architectural changes → use **SPIR** +- Complex features with multiple phases → use **SPIR** or **ASPIR** + +## Protocol Phases + +### I - Implement + +The builder reads the GitHub issue and implements the feature: + +1. Read and understand the issue requirements +2. Implement the feature (< 300 LOC) +3. Write tests +4. Verify build and tests pass +5. Commit with descriptive message + +If the feature grows beyond 300 LOC or requires architectural decisions, the builder signals `TOO_COMPLEX` to escalate to ASPIR. + +### R - Review (PR) + +The builder creates a PR with the review embedded in the PR body: + +1. Create PR linking to the issue +2. Include a review section in the PR body (summary, key decisions, test plan) +3. Optionally run CMAP consultation if the builder judges the complexity warrants it +4. Notify the architect + +The **PR gate** is preserved — a human reviews all code before merge. + +## Usage + +```bash +# Spawn a builder using AIR +af spawn 42 --protocol air + +# The builder implements autonomously and stops at the PR gate +``` + +## File Structure + +``` +codev-skeleton/protocols/air/ +├── protocol.json # Protocol definition +├── protocol.md # This file +├── builder-prompt.md # Builder instructions (Handlebars template) +├── prompts/ +│ ├── implement.md # Implement phase prompt +│ └── pr.md # PR phase prompt +└── consult-types/ + ├── impl-review.md # Implementation consultation guide + └── pr-review.md # PR consultation guide +``` diff --git a/codev/protocols/aspir/builder-prompt.md b/codev/protocols/aspir/builder-prompt.md new file mode 100644 index 0000000..1f932b6 --- /dev/null +++ b/codev/protocols/aspir/builder-prompt.md @@ -0,0 +1,75 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the protocol document yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Run consultations manually when the protocol calls for them +- You have flexibility in execution, but must stay compliant with the protocol +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals +- Do not deviate from the porch-driven workflow + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +- **NEVER skip the 3-way review** — always follow porch next → porch done cycle +- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval +{{/if}} + +## Protocol +Follow the SPIR protocol: `codev/protocols/spir/protocol.md` +Read and internalize the protocol before starting any work. + +{{#if spec}} +## Spec +Read the specification at: `{{spec.path}}` +{{/if}} + +{{#if plan}} +## Plan +Follow the implementation plan at: `{{plan.path}}` +{{/if}} + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} +{{/if}} + +{{#if task}} +## Task +{{task_text}} +{{/if}} + +## Notifications +Always use `af send architect "..."` to notify the architect at key moments: +- **Gate reached**: `af send architect "Project {{project_id}}: ready for approval"` +- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"` +- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."` +- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"` + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the protocol document thoroughly +2. Review the spec and plan (if available) +3. Begin implementation following the protocol phases diff --git a/codev/protocols/aspir/consult-types/impl-review.md b/codev/protocols/aspir/consult-types/impl-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/aspir/consult-types/impl-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/aspir/consult-types/phase-review.md b/codev/protocols/aspir/consult-types/phase-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/aspir/consult-types/phase-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/aspir/consult-types/plan-review.md b/codev/protocols/aspir/consult-types/plan-review.md new file mode 100644 index 0000000..585085d --- /dev/null +++ b/codev/protocols/aspir/consult-types/plan-review.md @@ -0,0 +1,59 @@ +# Plan Review Prompt + +## Context +You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +## Focus Areas + +1. **Spec Coverage** + - Does the plan address all requirements in the spec? + - Are there spec requirements not covered by any phase? + - Are there phases that go beyond the spec scope? + +2. **Phase Breakdown** + - Are phases appropriately sized (not too large or too small)? + - Is the sequence logical (dependencies respected)? + - Can each phase be completed and committed independently? + +3. **Technical Approach** + - Is the implementation approach sound? + - Are the right files/modules being modified? + - Are there obvious better approaches being missed? + +4. **Testability** + - Does each phase have clear test criteria? + - Will the Defend step (writing tests) be feasible? + - Are edge cases from the spec addressable? + +5. **Risk Assessment** + - Are there potential blockers not addressed? + - Are dependencies on other systems identified? + - Is the plan realistic given constraints? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Plan is ready for human review +- `REQUEST_CHANGES`: Significant issues with approach or coverage +- `COMMENT`: Minor suggestions, plan is workable but could improve + +## Notes + +- The spec has already been approved - don't re-litigate spec decisions +- Focus on the quality of the plan as a guide for builders +- Consider: Would a builder be able to follow this plan successfully? +- If referencing existing code, verify file paths seem accurate diff --git a/codev/protocols/aspir/consult-types/pr-review.md b/codev/protocols/aspir/consult-types/pr-review.md new file mode 100644 index 0000000..048c23f --- /dev/null +++ b/codev/protocols/aspir/consult-types/pr-review.md @@ -0,0 +1,72 @@ +# PR Ready Review Prompt + +## Context +You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. + +## Focus Areas + +1. **Completeness** + - Are all spec requirements implemented? + - Are all plan phases complete? + - Is the review document written (`codev/reviews/XXXX-name.md`)? + - Are all commits properly formatted (`[Spec XXXX][Phase]`)? + +2. **Test Status** + - Do all tests pass? + - Is test coverage adequate for the changes? + - Are there any skipped or flaky tests? + +3. **Code Cleanliness** + - Is there any debug code left in? + - Are there any TODO comments that should be resolved? + - Are there any `// REVIEW:` comments that weren't addressed? + - Is the code properly formatted? + +4. **Documentation** + - Are inline comments clear where needed? + - Is the review document comprehensive? + - Are any new APIs documented? + +5. **PR Readiness** + - Is the branch up to date with main? + - Are commits atomic and well-described? + - Is the change diff reasonable in size? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... + +PR_SUMMARY: | + ## Summary + [2-3 sentences describing what this PR does] + + ## Key Changes + - [Change 1] + - [Change 2] + + ## Test Plan + - [How to test] +``` + +**Verdict meanings:** +- `APPROVE`: Ready to create PR +- `REQUEST_CHANGES`: Issues to fix before PR creation +- `COMMENT`: Minor items, can create PR but note feedback + +## Notes + +- This is the builder's final self-review before hand-off +- The PR_SUMMARY in your output can be used as the PR description +- Focus on "is this ready for someone else to review" not "is this perfect" +- Any issues found here are cheaper to fix than during integration review diff --git a/codev/protocols/aspir/consult-types/spec-review.md b/codev/protocols/aspir/consult-types/spec-review.md new file mode 100644 index 0000000..7c9c157 --- /dev/null +++ b/codev/protocols/aspir/consult-types/spec-review.md @@ -0,0 +1,55 @@ +# Specification Review Prompt + +## Context +You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +## Focus Areas + +1. **Completeness** + - Are all requirements clearly stated? + - Are success criteria defined? + - Are edge cases considered? + - Is scope well-bounded (not too broad or vague)? + +2. **Correctness** + - Do requirements make sense technically? + - Are there contradictions? + - Is the problem statement accurate? + +3. **Feasibility** + - Can this be implemented with available tools/constraints? + - Are there obvious technical blockers? + - Is the scope realistic for a single spec? + +4. **Clarity** + - Would a builder understand what to build? + - Are acceptance criteria testable? + - Is terminology consistent? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Spec is ready for human review +- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but consider feedback + +## Notes + +- You are NOT reviewing code - you are reviewing the specification document +- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) +- Be constructive - identify issues AND suggest solutions +- If the spec references other specs, note if context seems missing diff --git a/codev/protocols/aspir/prompts/implement.md b/codev/protocols/aspir/prompts/implement.md new file mode 100644 index 0000000..bacc850 --- /dev/null +++ b/codev/protocols/aspir/prompts/implement.md @@ -0,0 +1,215 @@ +# IMPLEMENT Phase Prompt + +You are executing the **IMPLEMENT** phase of the SPIR protocol. + +## Your Goal + +Write clean, well-structured code AND tests that implement the current plan phase. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}} + +## ⚠️ SCOPE RESTRICTION — READ THIS FIRST + +**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).** + +- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations. +- **DO NOT** read the full plan file and implement everything you see. +- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope. +- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires. + +## What Happens After You Finish + +When you signal `PHASE_COMPLETE`, porch will: +1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation +2. Check that tests exist and pass +3. If reviewers request changes, you'll be respawned with their feedback +4. Once approved, porch commits and moves to the next plan phase + +## Spec Compliance (CRITICAL) + +**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".** + +### Trust Hierarchy + +``` +SPEC (source of truth) + ↓ +PLAN (implementation guide derived from spec) + ↓ +EXISTING CODE (NOT TRUSTED - must be validated against spec) +``` + +**Never trust existing code over the spec.** Previous implementations may have drifted. + +### Pre-Implementation Sanity Check (PISC) + +**Before writing ANY code:** + +1. ✅ "Have I read the spec in the last 30 minutes?" +2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?" +3. ✅ "Does my approach match the spec's Technical Implementation section?" +4. ✅ "If the spec has code examples, am I following them?" +5. ✅ "Does the existing code I'm building on actually match the spec?" + +**If ANY answer is "no" or "unsure" → STOP and re-read the spec.** + +### Avoiding "Fixing Mode" + +A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to: +- Cargo-culting patterns that may be wrong +- Building on broken foundations +- Implementing something different from the spec + +**When you catch yourself "fixing" code:** +1. STOP +2. Ask: "What does the spec say about this?" +3. Re-read the spec's Traps to Avoid section +4. Verify existing code matches the spec before building on it + +## Prerequisites + +Before implementing, verify: +1. Previous phase (if any) is committed to git +2. You've read the plan phase you're implementing +3. You understand the success criteria for this phase +4. Dependencies from earlier phases are available + +## Process + +### 1. Review the Plan Phase + +Read the current phase in the plan: +- What is the objective? +- What files need to be created/modified? +- What are the success criteria? +- What dependencies exist? + +### 2. Set Up + +- Verify you're on the correct branch +- Check that previous phase is committed: `git log --oneline -5` +- Ensure build passes before starting: `npm run build` (or equivalent) + +### 3. Implement the Code + +Write the code following these principles: + +**Code Quality Standards**: +- Self-documenting code (clear names, obvious structure) +- No commented-out code +- No debug prints in final code +- Explicit error handling +- Follow project style guide + +**Implementation Approach**: +- Work on one file at a time +- Make small, incremental changes +- Document complex logic with comments + +### 4. Write Tests + +**Tests are required.** For each piece of functionality you implement: + +- Write unit tests for core logic +- Write integration tests if the phase involves multiple components +- Test error cases and edge conditions +- Ensure tests are deterministic (no flaky tests) + +**Test file locations** (follow project conventions): +- `tests/` or `__tests__/` directories +- `*.test.ts` or `*.spec.ts` naming + +### 5. Verify Everything Works + +Run both build and tests: + +```bash +npm run build # Must pass +npm test # Must pass +``` + +**Important**: Don't assume these commands exist. Check `package.json` first. + +Fix any errors before signaling completion. + +### 6. Self-Review + +Before signaling completion: +- Read through all code changes +- Read through all test changes +- Verify code matches the spec requirements +- Ensure no accidental debug code +- Check test coverage is adequate + +## Output + +When complete, you should have: +- Modified/created source files as specified in the plan phase +- Tests covering the new functionality +- All build checks passing +- All tests passing + +## Signals + +When implementation AND tests are complete and passing: + +``` +PHASE_COMPLETE +``` + +If you encounter a blocker: + +``` +BLOCKED:reason goes here +``` + +If you need spec/plan clarification: + +``` + +Your specific questions here + +``` + +## Important Notes + +1. **Follow the plan** - Implement what's specified, not more +2. **Don't over-engineer** - Simplest solution that works +3. **Don't skip error handling** - But don't go overboard either +4. **Keep changes focused** - Only touch files in this phase +5. **Build AND tests must pass** - Don't signal complete until both pass +6. **Write tests** - Every implementation phase needs tests + +## What NOT to Do + +- Don't modify files outside this phase's scope +- Don't add features not in the spec +- Don't leave TODO comments for later (fix now or note as blocker) +- Don't skip writing tests +- Don't use `git add .` or `git add -A` when you commit (security risk) + +## Handling Problems + +**If the plan is unclear**: +Signal `AWAITING_INPUT` with your specific question. + +**If you discover the spec is wrong**: +Signal `BLOCKED` and explain the issue. The Architect may need to update the spec. + +**If a dependency is missing**: +Signal `BLOCKED` with details about what's missing. + +**If build or tests fail and you can't fix it**: +Signal `BLOCKED` with the error message. + +**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use workarounds to avoid the failure +3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up +5. Commit the skip and continue with your work diff --git a/codev/protocols/aspir/prompts/plan.md b/codev/protocols/aspir/prompts/plan.md new file mode 100644 index 0000000..3549654 --- /dev/null +++ b/codev/protocols/aspir/prompts/plan.md @@ -0,0 +1,150 @@ +# PLAN Phase Prompt + +You are executing the **PLAN** phase of the SPIR protocol. + +## Your Goal + +Transform the approved specification into an executable implementation plan with clear phases. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` +- **Plan File**: `codev/plans/{{artifact_name}}.md` + +## Prerequisites + +Before planning, verify: +1. The specification exists and has been approved +2. You've read and understood the entire spec +3. Success criteria are clear and measurable + +## Process + +### 1. Analyze the Specification + +Read the spec thoroughly. Identify: +- All functional requirements +- Non-functional requirements +- Dependencies and constraints +- Success criteria to validate against + +### 2. Identify Implementation Phases + +Break the work into logical phases. Each phase should be: +- **Self-contained** - A complete unit of functionality +- **Independently testable** - Can be verified on its own +- **Valuable** - Delivers observable progress +- **Committable** - Can be a single atomic commit + +Good phase examples: +- "Database Schema" - Creates all tables/migrations +- "Core API Endpoints" - Implements main REST routes +- "Authentication Flow" - Handles login/logout/session + +Bad phase examples: +- "Setup" - Too vague +- "Part 1" - Not descriptive +- "Everything" - Not broken down + +### 3. Define Each Phase + +For each phase, document: +- **Objective** - Single clear goal +- **Files to modify/create** - Specific paths +- **Dependencies** - Which phases must complete first +- **Success criteria** - How to know it's done +- **Test approach** - What tests will verify it + +### 4. Order Phases by Dependencies + +Arrange phases so dependencies are satisfied: +``` +Phase 1: Database Schema (no dependencies) +Phase 2: Data Models (depends on Phase 1) +Phase 3: API Endpoints (depends on Phase 2) +Phase 4: Frontend Integration (depends on Phase 3) +``` + +### 5. Finalize + +After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + +## Output + +Create the plan file at `codev/plans/{{artifact_name}}.md`. + +Use the plan template from `codev/protocols/spir/templates/plan.md` if available. + +### Plan Structure + +```markdown +# Implementation Plan: {{title}} + +## Overview +Brief summary of what will be implemented. + +## Phases + +### Phase 1: [Name] +- **Objective**: [Single clear goal] +- **Files**: [List of files to create/modify] +- **Dependencies**: None +- **Success Criteria**: [How to verify completion] +- **Tests**: [What tests will be written] + +### Phase 2: [Name] +- **Objective**: [Single clear goal] +- **Files**: [List of files] +- **Dependencies**: Phase 1 +- **Success Criteria**: [Verification method] +- **Tests**: [Test approach] + +[Continue for all phases...] + +## Risk Assessment +- [Risk 1]: [Mitigation] +- [Risk 2]: [Mitigation] + +``` + +## Signals + +Emit appropriate signals based on your progress: + +- After completing the plan draft: + ``` + PLAN_DRAFTED + ``` + +## Commit Cadence + +Make commits at these milestones: +1. `[Spec {{project_id}}] Initial implementation plan` +2. `[Spec {{project_id}}] Plan with multi-agent review` +3. `[Spec {{project_id}}] Plan with user feedback` +4. `[Spec {{project_id}}] Final approved plan` + +**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: +```bash +git add codev/plans/{{artifact_name}}.md +``` + +## Important Notes + +1. **No time estimates** - Don't include hours/days/weeks +3. **Be specific about files** - Exact paths, not "the config file" +4. **Keep phases small** - 1-3 files per phase is ideal +5. **Document dependencies clearly** - Prevents blocked work + +## What NOT to Do + +- Don't run `consult` commands yourself (porch handles consultations) +- Don't write code (that's for Implement phase) +- Don't estimate time (meaningless in AI development) +- Don't create phases that can't be independently tested +- Don't skip dependency analysis +- Don't make phases too large (if >5 files, split it) +- Don't use `git add .` or `git add -A` (security risk) diff --git a/codev/protocols/aspir/prompts/review.md b/codev/protocols/aspir/prompts/review.md new file mode 100644 index 0000000..dbffd4b --- /dev/null +++ b/codev/protocols/aspir/prompts/review.md @@ -0,0 +1,259 @@ +# REVIEW Phase Prompt + +You are executing the **REVIEW** phase of the SPIR protocol. + +## Your Goal + +Perform a comprehensive review, document lessons learned, and prepare for PR submission. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` +- **Plan File**: `codev/plans/{{artifact_name}}.md` +- **Review File**: `codev/reviews/{{artifact_name}}.md` + +## Prerequisites + +Before review, verify: +1. All implementation phases are committed +2. All tests are passing +3. Build is passing +4. Spec compliance verified for all phases + +Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"` + +## Process + +### 1. Comprehensive Review + +Review the entire implementation: + +**Code Quality**: +- Is the code readable and maintainable? +- Are there any code smells? +- Is error handling consistent? +- Are there any security concerns? + +**Architecture**: +- Does the implementation fit well with existing code? +- Are there any architectural concerns? +- Is the design scalable if needed? + +**Documentation**: +- Is code adequately commented where needed? +- Are public APIs documented? +- Is README updated if needed? + +### 2. Spec Comparison + +Compare final implementation to original specification: + +- What was delivered vs what was specified? +- Any deviations? Document why. +- All success criteria met? + +### 3. Create Review Document + +Create `codev/reviews/{{artifact_name}}.md`: + +```markdown +# Review: {{title}} + +## Summary +Brief description of what was implemented. + +## Spec Compliance +- [x] Requirement 1: Implemented as specified +- [x] Requirement 2: Implemented with deviation (see below) +- [x] Requirement 3: Implemented as specified + +## Deviations from Plan +- **Phase X**: [What changed and why] + +## Lessons Learned + +### What Went Well +- [Positive observation 1] +- [Positive observation 2] + +### Challenges Encountered +- [Challenge 1]: [How it was resolved] +- [Challenge 2]: [How it was resolved] + +### What Would Be Done Differently +- [Insight 1] +- [Insight 2] + +### Methodology Improvements +- [Suggested improvement to SPIR protocol] +- [Suggested improvement to tooling] + +## Technical Debt +- [Any shortcuts taken that should be addressed later] + +## Consultation Feedback + +[See instructions below] + +## Flaky Tests +- [Any pre-existing tests that were skipped as flaky during this project] +- [Include test name, file path, and observed failure mode] +- [If none: "No flaky tests encountered"] + +## Follow-up Items +- [Any items identified for future work] +``` + +### 3b. Include Consultation Feedback + +**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. + +Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: + +```markdown +## Consultation Feedback + +### Specify Phase (Round 1) + +#### Gemini +- **Concern**: [Summary of the concern] + - **Addressed**: [What was changed to resolve it] + +#### Codex +- **Concern**: [Summary] + - **Rebutted**: [Why the current approach is correct] + +#### Claude +- No concerns raised (APPROVE) + +### Plan Phase (Round 1) +... +``` + +**Response types** — each concern gets exactly one: +- **Addressed**: Builder made a change to resolve the concern +- **Rebutted**: Builder explains why the concern doesn't apply +- **N/A**: Concern is out of scope, already handled elsewhere, or moot + +**Edge cases**: +- If all reviewers approved with no concerns: "No concerns raised — all consultations approved" +- For COMMENT verdicts: include their feedback (non-blocking but useful context) +- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" +- If a phase had multiple rounds, give each round its own subsection + +### 4. Update Architecture and Lessons Learned Documentation + +**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. + +**Architecture Updates** (`codev/resources/arch.md`): +1. Read the current `codev/resources/arch.md` +2. Determine if this project introduced architectural changes worth documenting (new subsystems, data flows, design decisions, invariants, file locations) +3. If yes: make the updates to arch.md and describe what you changed in the `## Architecture Updates` section of the review +4. If no: write "No architecture updates needed" in the section with a brief explanation (e.g., "This was a template-only change with no new subsystems or data flows") + +**Lessons Learned Updates** (`codev/resources/lessons-learned.md`): +1. Read the current `codev/resources/lessons-learned.md` +2. Determine if this project produced generalizable lessons (patterns, anti-patterns, debugging insights, process improvements) +3. If yes: add entries to lessons-learned.md and describe what you added in the `## Lessons Learned Updates` section of the review +4. If no: write "No lessons learned updates needed" in the section with a brief explanation (e.g., "Straightforward implementation with no novel insights beyond existing entries") + +### 4b. Update Other Documentation + +If needed, also update: +- README.md (new features, changed behavior) +- API documentation + +### 5. Final Verification + +Before PR: +- [ ] All tests pass (use project-specific test command) +- [ ] Build passes (use project-specific build command) +- [ ] Lint passes (if configured) +- [ ] No uncommitted changes: `git status` +- [ ] Review document complete + +### 6. Create Pull Request + +**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that +porch consultation reviews the actual PR, and the architect can review a real PR +when the pr gate fires. + +```bash +gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF' +## Summary +[Brief description of the implementation] + +## Changes +- [Change 1] +- [Change 2] + +## Testing +- All unit tests passing +- Integration tests added for [X] +- Manual testing completed for [Y] + +## Spec +Link: codev/specs/{{artifact_name}}.md + +## Review +Link: codev/reviews/{{artifact_name}}.md +EOF +)" +``` + +### 7. Signal Completion + +After the PR is created, signal completion. Porch will run 3-way consultation +(Gemini, Codex, Claude) automatically via the verify step. If reviewers request +changes, you'll be respawned with their feedback. + +## Output + +- Review document at `codev/reviews/{{artifact_name}}.md` +- Updated documentation (if needed) +- Pull request created and ready for review + +## Signals + +- After review document is complete: + ``` + REVIEW_COMPLETE + ``` + +- After PR is created — signal completion so porch runs consultation: + ``` + PR_READY + ``` + +## Important Notes + +1. **Be honest in lessons learned** - Future you will thank present you +3. **Document deviations** - They're not failures, they're learnings +4. **Update methodology** - If you found a better way, document it +5. **Don't skip the checklist** - It catches last-minute issues +6. **Clean PR description** - Makes review easier + +## What NOT to Do + +- Don't run `consult` commands yourself (porch handles consultations) +- Don't skip lessons learned ("nothing to report") +- Don't merge your own PR (Architect handles integration) +- Don't leave uncommitted changes +- Don't forget to update documentation +- Don't rush this phase - it's valuable for learning +- Don't use `git add .` or `git add -A` (security risk) + +## Review Prompts for Reflection + +Ask yourself: +- What surprised me during implementation? +- Where did I spend the most time? Was it avoidable? +- What would have helped me go faster? +- Did the spec adequately describe what was needed? +- Did the plan phases make sense in hindsight? +- What tests caught issues? What tests were unnecessary? + +Capture these reflections in the lessons learned section. diff --git a/codev/protocols/aspir/prompts/specify.md b/codev/protocols/aspir/prompts/specify.md new file mode 100644 index 0000000..6da1868 --- /dev/null +++ b/codev/protocols/aspir/prompts/specify.md @@ -0,0 +1,139 @@ +# SPECIFY Phase Prompt + +You are executing the **SPECIFY** phase of the SPIR protocol. + +## Your Goal + +Create a comprehensive specification document that thoroughly explores the problem space and proposed solution. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` + +## Process + +### 0. Check for Existing Spec (ALWAYS DO THIS FIRST) + +**Before asking ANY questions**, check if a spec already exists: + +```bash +ls codev/specs/{{project_id}}-*.md +``` + +**If a spec file exists:** +1. READ IT COMPLETELY - the answers to your questions are already there +2. The spec author has already made the key decisions +3. DO NOT ask clarifying questions - proceed directly to consultation +4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch + +**If no spec exists:** Proceed to Step 1 below. + +### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS) + +Before writing anything, ask clarifying questions to understand: +- What problem is being solved? +- Who are the stakeholders? +- What are the constraints? +- What's in scope vs out of scope? +- What does success look like? + +If this is your first iteration AND no spec exists, ask these questions now and wait for answers. + +**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer. + +**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step. + +### 2. Problem Analysis + +Once you have answers, document: +- The problem being solved (clearly articulated) +- Current state vs desired state +- Stakeholders and their needs +- Assumptions and constraints + +### 3. Solution Exploration + +Generate multiple solution approaches. For each: +- Technical design overview +- Trade-offs (pros/cons) +- Complexity assessment +- Risk assessment + +### 4. Open Questions + +List uncertainties categorized as: +- **Critical** - blocks progress +- **Important** - affects design +- **Nice-to-know** - optimization + +### 5. Success Criteria + +Define measurable acceptance criteria: +- Functional requirements (MUST, SHOULD, COULD) +- Non-functional requirements (performance, security) +- Test scenarios + +### 6. Finalize + +After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + +## Output + +Create or update the specification file at `codev/specs/{{artifact_name}}.md`. + +**IMPORTANT**: Keep spec/plan/review filenames in sync: +- Spec: `codev/specs/{{artifact_name}}.md` +- Plan: `codev/plans/{{artifact_name}}.md` +- Review: `codev/reviews/{{artifact_name}}.md` + +## Signals + +Emit appropriate signals based on your progress: + +- When waiting for clarifying question answers, **include your questions in the signal**: + ``` + + Please answer these questions: + 1. What should the primary use case be - internal tooling or customer-facing? + 2. What are the key constraints we should consider? + 3. Who are the main stakeholders? + + ``` + + The content inside the signal tag is displayed prominently to the user. + +- After completing the initial spec draft: + ``` + SPEC_DRAFTED + ``` + + +## Commit Cadence + +Make commits at these milestones: +1. `[Spec {{project_id}}] Initial specification draft` +2. `[Spec {{project_id}}] Specification with multi-agent review` +3. `[Spec {{project_id}}] Specification with user feedback` +4. `[Spec {{project_id}}] Final approved specification` + +**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: +```bash +git add codev/specs/{{artifact_name}}.md +``` + +## Important Notes + +1. **Be thorough** - A good spec prevents implementation problems +3. **Be specific** - Vague specs lead to wrong implementations +4. **Include examples** - Concrete examples clarify intent + +## What NOT to Do + +- Don't run `consult` commands yourself (porch handles consultations) +- Don't include implementation details (that's for the Plan phase) +- Don't estimate time (AI makes time estimates meaningless) +- Don't start coding (you're in Specify, not Implement) +- Don't use `git add .` or `git add -A` (security risk) diff --git a/codev/protocols/aspir/protocol.json b/codev/protocols/aspir/protocol.json new file mode 100644 index 0000000..713fec3 --- /dev/null +++ b/codev/protocols/aspir/protocol.json @@ -0,0 +1,161 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "aspir", + "version": "1.0.0", + "description": "ASPIR: Autonomous SPIR — Specify → Plan → Implement → Review without human approval gates", + "input": { + "type": "spec", + "required": false, + "default_for": ["--project", "-p"] + }, + "phases": [ + { + "id": "specify", + "name": "Specify", + "description": "Write specification with 3-way review", + "type": "build_verify", + "build": { + "prompt": "specify.md", + "artifact": "codev/specs/${PROJECT_TITLE}.md" + }, + "verify": { + "type": "spec", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "next": "plan" + }, + { + "id": "plan", + "name": "Plan", + "description": "Write implementation plan with 3-way review", + "type": "build_verify", + "build": { + "prompt": "plan.md", + "artifact": "codev/plans/${PROJECT_TITLE}.md" + }, + "verify": { + "type": "plan", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md", + "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md", + "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'" + }, + "next": "implement" + }, + { + "id": "implement", + "name": "Implement", + "description": "Implement code with 3-way review per plan phase", + "type": "per_plan_phase", + "build": { + "prompt": "implement.md", + "artifact": "src/**/*.{ts,tsx,js,jsx}" + }, + "verify": { + "type": "impl", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + }, + "tests": { + "command": "npm test -- --exclude='**/e2e/**'", + "description": "Unit tests only - e2e tests run in review phase", + "on_fail": "retry", + "max_retries": 2 + } + }, + "transition": { + "on_complete": "implement", + "on_all_phases_complete": "review" + } + }, + { + "id": "review", + "name": "Review", + "description": "Final review and PR with 3-way review", + "type": "build_verify", + "build": { + "prompt": "review.md", + "artifact": "codev/reviews/${PROJECT_TITLE}.md" + }, + "verify": { + "type": "pr", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "pr_exists": { + "command": "gh pr list --state all --head \"$(git branch --show-current)\" --json number --jq 'length' | grep -q '^[1-9]'", + "description": "PR must be created before signaling completion" + }, + "review_has_arch_updates": { + "command": "grep -q '## Architecture Updates' codev/reviews/${PROJECT_TITLE}.md", + "description": "Review must include '## Architecture Updates' section (what changed in arch.md, or why no changes needed)" + }, + "review_has_lessons_updates": { + "command": "grep -q '## Lessons Learned Updates' codev/reviews/${PROJECT_TITLE}.md", + "description": "Review must include '## Lessons Learned Updates' section (what changed in lessons-learned.md, or why no changes needed)" + }, + "e2e_tests": { + "command": "npm run test:e2e 2>&1 || echo 'e2e tests skipped (not configured)'", + "description": "Full e2e test suite - only runs in review phase", + "optional": true + } + }, + "gate": "pr", + "next": null + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current build phase is complete", + "transitions_to": "verify" + }, + "BLOCKED": { + "description": "Signal implementation is blocked", + "requires": "reason" + } + }, + "phase_completion": { + "build_succeeds": "npm run build 2>&1", + "tests_pass": "npm test 2>&1", + "commit_has_code": "git log -1 --name-only --pretty=format: | grep -qE '\\.(ts|tsx|js|jsx|py|go|rs)$'" + }, + "defaults": { + "mode": "strict", + "max_iterations": 1, + "verify": { + "models": ["gemini", "codex", "claude"], + "parallel": true + } + } +} diff --git a/codev/protocols/aspir/protocol.md b/codev/protocols/aspir/protocol.md new file mode 100644 index 0000000..435bcb4 --- /dev/null +++ b/codev/protocols/aspir/protocol.md @@ -0,0 +1,94 @@ +# ASPIR Protocol + +> **ASPIR** = **A**utonomous **S**pecify → **P**lan → **I**mplement → **R**eview +> +> Identical to SPIR but without human approval gates on spec and plan phases. +> Each phase has one build-verify cycle with 3-way consultation. + +## What is ASPIR? + +ASPIR is an autonomous variant of the SPIR protocol. It follows the exact same phases (Specify → Plan → Implement → Review) with the same 3-way consultations, checks, and PR flow — but removes the `spec-approval` and `plan-approval` human gates. + +This means the builder proceeds automatically from Specify → Plan → Implement without waiting for human approval at each gate. The `pr` gate in the Review phase is preserved — a human still reviews all code before merge. + +### Differences from SPIR + +| Aspect | SPIR | ASPIR | +|--------|------|-------| +| Spec gate (`spec-approval`) | Human must approve | Auto-approved | +| Plan gate (`plan-approval`) | Human must approve | Auto-approved | +| PR gate (`pr`) | Human must approve | Human must approve | +| Phases | Specify → Plan → Implement → Review | Same | +| 3-way consultations | Yes, every phase | Same | +| Checks (build, tests, PR) | Yes | Same | +| Prompts / templates | Full set | Same (copied from SPIR) | + +### When to Use ASPIR + +Use ASPIR instead of SPIR when: + +- The work is **trusted and low-risk** — internal tooling, protocol additions, well-understood features +- The architect has **pre-written and approved** the spec before spawning +- The scope is **self-contained** with low blast radius +- You want **full SPIR discipline** (consultations, phased implementation, review) without waiting at gates + +### When NOT to Use ASPIR + +Use SPIR instead when: + +- The feature involves **novel architecture** or unclear requirements +- The spec needs **iterative human feedback** during drafting +- The work is **high-risk** — security-sensitive, user-facing, or broadly impactful +- You want to **review and adjust** the plan before implementation starts + +## Protocol Phases + +ASPIR follows the same four phases as SPIR. For full phase documentation, see the [SPIR protocol](../spir/protocol.md). + +### S - Specify +Write specification with 3-way review (Gemini, Codex, Claude). **No human gate** — proceeds directly to Plan after verification. + +### P - Plan +Write implementation plan with 3-way review. **No human gate** — proceeds directly to Implement after verification and checks pass. + +### I - Implement +Execute each plan phase with build-verify cycle. Same as SPIR — no gate between phases (SPIR also has no gate here). + +### R - Review +Final review, PR preparation, and 3-way review. **PR gate preserved** — builder stops and waits for human approval before merge. + +## Usage + +```bash +# Spawn a builder using ASPIR +af spawn 42 --protocol aspir + +# The builder runs autonomously through Specify → Plan → Implement +# and stops only at the PR gate in the Review phase +``` + +## File Structure + +``` +codev/protocols/aspir/ +├── protocol.json # Protocol definition (SPIR minus gates) +├── protocol.md # This file +├── builder-prompt.md # Builder instructions (same as SPIR) +├── prompts/ +│ ├── specify.md # Specify phase prompt (same as SPIR) +│ ├── plan.md # Plan phase prompt (same as SPIR) +│ ├── implement.md # Implement phase prompt (same as SPIR) +│ └── review.md # Review phase prompt (same as SPIR) +├── consult-types/ +│ ├── spec-review.md # Spec consultation guide (same as SPIR) +│ ├── plan-review.md # Plan consultation guide (same as SPIR) +│ ├── impl-review.md # Impl consultation guide (same as SPIR) +│ ├── phase-review.md # Phase consultation guide (same as SPIR) +│ └── pr-review.md # PR consultation guide (same as SPIR) +└── templates/ + ├── spec.md # Spec template (same as SPIR) + ├── plan.md # Plan template (same as SPIR) + └── review.md # Review template (same as SPIR) +``` + +All files except `protocol.json` and `protocol.md` are identical to their SPIR counterparts. diff --git a/codev/protocols/aspir/templates/plan.md b/codev/protocols/aspir/templates/plan.md new file mode 100644 index 0000000..8311998 --- /dev/null +++ b/codev/protocols/aspir/templates/plan.md @@ -0,0 +1,204 @@ +# Plan: [Title] + +## Metadata +- **ID**: plan-[YYYY-MM-DD]-[short-name] +- **Status**: draft +- **Specification**: [Link to codev/specs/spec-file.md] +- **Created**: [YYYY-MM-DD] + +## Executive Summary +[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.] + +## Success Metrics +[Copy from specification and add implementation-specific metrics] +- [ ] All specification criteria met +- [ ] Test coverage >90% +- [ ] Performance benchmarks achieved +- [ ] Zero critical security issues +- [ ] Documentation complete + +## Phases (Machine Readable) + + + +```json +{ + "phases": [ + {"id": "phase_1", "title": "Phase 1 Title Here"}, + {"id": "phase_2", "title": "Phase 2 Title Here"}, + {"id": "phase_3", "title": "Phase 3 Title Here"} + ] +} +``` + +## Phase Breakdown + +### Phase 1: [Descriptive Name] +**Dependencies**: None + +#### Objectives +- [Clear, single objective for this phase] +- [What value does this phase deliver?] + +#### Deliverables +- [ ] [Specific deliverable 1] +- [ ] [Specific deliverable 2] +- [ ] [Tests for this phase] +- [ ] [Documentation updates] + +#### Implementation Details +[Specific technical approach for this phase. Include: +- Key files/modules to create or modify +- Architectural decisions +- API contracts +- Data models] + +#### Acceptance Criteria +- [ ] [Testable criterion 1] +- [ ] [Testable criterion 2] +- [ ] All tests pass +- [ ] Code review completed + +#### Test Plan +- **Unit Tests**: [What to test] +- **Integration Tests**: [What to test] +- **Manual Testing**: [Scenarios to verify] + +#### Rollback Strategy +[How to revert this phase if issues arise] + +#### Risks +- **Risk**: [Specific risk for this phase] + - **Mitigation**: [How to address] + +--- + +### Phase 2: [Descriptive Name] +**Dependencies**: Phase 1 + +[Repeat structure for each phase] + +--- + +### Phase 3: [Descriptive Name] +**Dependencies**: Phase 2 + +[Continue for all phases] + +## Dependency Map +``` +Phase 1 ──→ Phase 2 ──→ Phase 3 + ↓ + Phase 4 (optional) +``` + +## Resource Requirements +### Development Resources +- **Engineers**: [Expertise needed] +- **Environment**: [Dev/staging requirements] + +### Infrastructure +- [Database changes] +- [New services] +- [Configuration updates] +- [Monitoring additions] + +## Integration Points +### External Systems +- **System**: [Name] + - **Integration Type**: [API/Database/Message Queue] + - **Phase**: [Which phase needs this] + - **Fallback**: [What if unavailable] + +### Internal Systems +[Repeat structure] + +## Risk Analysis +### Technical Risks +| Risk | Probability | Impact | Mitigation | Owner | +|------|------------|--------|------------|-------| +| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | + +### Schedule Risks +| Risk | Probability | Impact | Mitigation | Owner | +|------|------------|--------|------------|-------| +| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | + +## Validation Checkpoints +1. **After Phase 1**: [What to validate] +2. **After Phase 2**: [What to validate] +3. **Before Production**: [Final checks] + +## Monitoring and Observability +### Metrics to Track +- [Metric 1: Description and threshold] +- [Metric 2: Description and threshold] + +### Logging Requirements +- [What to log and at what level] +- [Retention requirements] + +### Alerting +- [Alert condition and severity] +- [Who to notify] + +## Documentation Updates Required +- [ ] API documentation +- [ ] Architecture diagrams +- [ ] Runbooks +- [ ] User guides +- [ ] Configuration guides + +## Post-Implementation Tasks +- [ ] Performance validation +- [ ] Security audit +- [ ] Load testing +- [ ] User acceptance testing +- [ ] Monitoring validation + +## Expert Review +**Date**: [YYYY-MM-DD] +**Model**: [Model consulted] +**Key Feedback**: +- [Feasibility assessment] +- [Missing considerations] +- [Risk identification] +- [Alternative suggestions] + +**Plan Adjustments**: +- [How the plan was modified based on feedback] + +## Approval +- [ ] Technical Lead Review +- [ ] Engineering Manager Approval +- [ ] Resource Allocation Confirmed +- [ ] Expert AI Consultation Complete + +## Change Log +| Date | Change | Reason | Author | +|------|--------|--------|--------| +| [Date] | [What changed] | [Why] | [Who] | + +## Notes +[Additional context, assumptions, or considerations] + +--- + +## Amendment History + +This section tracks all TICK amendments to this plan. TICKs modify both the spec and plan together as an atomic unit. + + + + \ No newline at end of file diff --git a/codev/protocols/aspir/templates/review.md b/codev/protocols/aspir/templates/review.md new file mode 100644 index 0000000..eaaf682 --- /dev/null +++ b/codev/protocols/aspir/templates/review.md @@ -0,0 +1,120 @@ +# Review: [Feature/Project Name] + +## Summary + +[1-3 sentences: what was built, how many phases, net outcome.] + +## Spec Compliance + +- [x] AC1: [Description] (Phase N) +- [x] AC2: [Description] (Phase N) +- [ ] ACn: [Not met — reason] + +## Deviations from Plan + +- **Phase N**: [What changed and why] + +## Key Metrics + +- **Commits**: [N] on the branch +- **Tests**: [N] passing ([N] existing + [N] new) +- **Files created**: [list] +- **Files deleted**: [list] +- **Net LOC impact**: [+/-N lines] + +## Timelog + +All times [timezone], [date range]. + +| Time | Event | +|------|-------| +| HH:MM | First commit: [description] | +| HH:MM | [Phase/milestone] | +| — | **GATE: [gate-name]** (human approval required) | +| HH:MM | Implementation begins | +| HH:MM | Phase N complete after N iterations | +| HH:MM | **GATE: pr** | + +### Autonomous Operation + +| Period | Duration | Activity | +|--------|----------|----------| +| Spec + Plan | ~Nm | [Summary] | +| Human gate wait | ~Nh Nm | Idle — waiting for approval | +| Implementation → PR | ~Nh Nm | N phases, N consultation rounds | + +**Total wall clock** (first commit to pr): **Xh Ym** +**Total autonomous work time** (excluding gate waits): **~Xh Ym** +**Context window resets**: [N] (resumed automatically / required manual restart) + +## Consultation Iteration Summary + +[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT. + +| Phase | Iters | Who Blocked | What They Caught | +|-------|-------|-------------|------------------| +| Specify | N | [Model] | [Brief description] | +| Plan | N | [Model] | [Brief description] | +| Phase 1 | N | [Model] | [Brief description] | +| Phase N | N | [Model] | [Brief description] | +| Review | N | [Model] | [Brief description] | + +**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern]. + +### Avoidable Iterations + +Iterations that could have been prevented with better builder behavior: + +1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."] + +2. **[Pattern]**: [Another avoidable iteration pattern.] + +## Consultation Feedback + +[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."] + +### [Phase] Phase (Round N) + +#### Gemini +- **Concern**: [Summary of concern] + - **Addressed**: [What was changed] + +#### Codex +- **Concern**: [Summary of concern] + - **Rebutted**: [Why current approach is correct] + +#### Claude +- No concerns raised (APPROVE) + +## Lessons Learned + +### What Went Well +- [Specific positive observation — what worked and why] + +### Challenges Encountered +- **[Challenge]**: [How it was resolved. How many iterations it cost.] + +### What Would Be Done Differently +- [Actionable improvement for future builders] + +## Architecture Updates + +[What was added/changed in `codev/resources/arch.md`, or why no changes were needed.] + +- Updated: [section name] — [what was added/changed] +- Or: "No architecture updates needed — [brief reason]" + +## Lessons Learned Updates + +[What was added/changed in `codev/resources/lessons-learned.md`, or why no changes were needed.] + +- Added: [category] — [lesson summary] +- Or: "No lessons learned updates needed — [brief reason]" + +## Technical Debt + +- [Any shortcuts taken or inconsistencies introduced] + +## Follow-up Items + +- [Items identified for future work, outside this spec's scope] diff --git a/codev/protocols/aspir/templates/spec.md b/codev/protocols/aspir/templates/spec.md new file mode 100644 index 0000000..03c1731 --- /dev/null +++ b/codev/protocols/aspir/templates/spec.md @@ -0,0 +1,182 @@ +# Specification: [Title] + + + +## Metadata +- **ID**: spec-[YYYY-MM-DD]-[short-name] +- **Status**: draft +- **Created**: [YYYY-MM-DD] + +## Clarifying Questions Asked + +[List the questions you asked to understand the problem better and the responses received. This shows the discovery process.] + +## Problem Statement +[Clearly articulate the problem being solved. Include context about why this is important, who is affected, and what the current pain points are.] + +## Current State +[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.] + +## Desired State +[Describe the ideal solution. How should things work after implementation? What specific improvements will users see?] + +## Stakeholders +- **Primary Users**: [Who will directly use this feature?] +- **Secondary Users**: [Who else is affected?] +- **Technical Team**: [Who will implement and maintain this?] +- **Business Owners**: [Who has decision authority?] + +## Success Criteria +- [ ] [Specific, measurable criterion 1] +- [ ] [Specific, measurable criterion 2] +- [ ] [Specific, measurable criterion 3] +- [ ] All tests pass with >90% coverage +- [ ] Performance benchmarks met (specify below) +- [ ] Documentation updated + +## Constraints +### Technical Constraints +- [Existing system limitations] +- [Technology stack requirements] +- [Integration points] + +### Business Constraints +- [Timeline requirements] +- [Budget considerations] +- [Compliance requirements] + +## Assumptions +- [List assumptions being made] +- [Include dependencies on other work] +- [Note any prerequisites] + +## Solution Approaches + +### Approach 1: [Name] +**Description**: [Brief overview of this approach] + +**Pros**: +- [Advantage 1] +- [Advantage 2] + +**Cons**: +- [Disadvantage 1] +- [Disadvantage 2] + +**Estimated Complexity**: [Low/Medium/High] +**Risk Level**: [Low/Medium/High] + +### Approach 2: [Name] +[Repeat structure for additional approaches] + +[Add as many approaches as appropriate for the problem] + +## Open Questions + +### Critical (Blocks Progress) +- [ ] [Question that must be answered before proceeding] + +### Important (Affects Design) +- [ ] [Question that influences technical decisions] + +### Nice-to-Know (Optimization) +- [ ] [Question that could improve the solution] + +## Performance Requirements +- **Response Time**: [e.g., <200ms p95] +- **Throughput**: [e.g., 1000 requests/second] +- **Resource Usage**: [e.g., <500MB memory] +- **Availability**: [e.g., 99.9% uptime] + +## Security Considerations +- [Authentication requirements] +- [Authorization model] +- [Data privacy concerns] +- [Audit requirements] + +## Test Scenarios +### Functional Tests +1. [Scenario 1: Happy path] +2. [Scenario 2: Edge case] +3. [Scenario 3: Error condition] + +### Non-Functional Tests +1. [Performance test scenario] +2. [Security test scenario] +3. [Load test scenario] + +## Dependencies +- **External Services**: [List any external APIs or services] +- **Internal Systems**: [List internal dependencies] +- **Libraries/Frameworks**: [List required libraries] + +## References +- [Link to relevant documentation in codev/ref/] +- [Link to related specifications] +- [Link to architectural diagrams] +- [Link to research materials] + +## Risks and Mitigation +| Risk | Probability | Impact | Mitigation Strategy | +|------|------------|--------|-------------------| +| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] | +| [Risk 2] | Low/Med/High | Low/Med/High | [How to address] | + +## Expert Consultation + +**Date**: [YYYY-MM-DD] +**Models Consulted**: [e.g., GPT-5 and Gemini Pro] +**Sections Updated**: +- [Section name]: [Brief description of change based on consultation] +- [Section name]: [Brief description of change based on consultation] + +Note: All consultation feedback has been incorporated directly into the relevant sections above. + +## Approval +- [ ] Technical Lead Review +- [ ] Product Owner Review +- [ ] Stakeholder Sign-off +- [ ] Expert AI Consultation Complete + +## Notes +[Any additional context or considerations not covered above] + +--- + +## Amendments + +This section tracks all TICK amendments to this specification. TICKs are lightweight changes that refine an existing spec rather than creating a new one. + + + + \ No newline at end of file diff --git a/codev/protocols/bugfix/builder-prompt.md b/codev/protocols/bugfix/builder-prompt.md new file mode 100644 index 0000000..0fa47ee --- /dev/null +++ b/codev/protocols/bugfix/builder-prompt.md @@ -0,0 +1,69 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the BUGFIX protocol yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Run consultations manually when the protocol calls for them +- You have flexibility in execution, but must stay compliant with the protocol +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +- **NEVER skip the 3-way review** — always follow porch next → porch done cycle +{{/if}} + +## Protocol +Follow the BUGFIX protocol: `codev/protocols/bugfix/protocol.md` + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} + +## Your Mission +1. Reproduce the bug +2. Identify root cause +3. Implement fix (< 300 LOC) +4. Add regression test +5. Create PR with "Fixes #{{issue.number}}" in body +6. Notify architect via `af send architect "PR #N ready for review (fixes #{{issue.number}})"` + +If the fix is too complex (> 300 LOC or architectural changes), notify the Architect via: +```bash +af send architect "Issue #{{issue.number}} is more complex than expected. [Reason]. Recommend escalating to SPIR/TICK." +``` + +## Notifications +Always use `af send architect "..."` to notify the architect at key moments: +- **PR ready**: `af send architect "PR #N ready for review (fixes #{{issue.number}})"` +- **PR merged**: `af send architect "PR #N merged for issue #{{issue.number}}. Ready for cleanup."` +- **Blocked**: `af send architect "Blocked on issue #{{issue.number}}: [reason]"` +{{/if}} + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the BUGFIX protocol +2. Review the issue details +3. Reproduce the bug before fixing diff --git a/codev/protocols/bugfix/consult-types/impl-review.md b/codev/protocols/bugfix/consult-types/impl-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/bugfix/consult-types/impl-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/bugfix/consult-types/pr-review.md b/codev/protocols/bugfix/consult-types/pr-review.md new file mode 100644 index 0000000..048c23f --- /dev/null +++ b/codev/protocols/bugfix/consult-types/pr-review.md @@ -0,0 +1,72 @@ +# PR Ready Review Prompt + +## Context +You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. + +## Focus Areas + +1. **Completeness** + - Are all spec requirements implemented? + - Are all plan phases complete? + - Is the review document written (`codev/reviews/XXXX-name.md`)? + - Are all commits properly formatted (`[Spec XXXX][Phase]`)? + +2. **Test Status** + - Do all tests pass? + - Is test coverage adequate for the changes? + - Are there any skipped or flaky tests? + +3. **Code Cleanliness** + - Is there any debug code left in? + - Are there any TODO comments that should be resolved? + - Are there any `// REVIEW:` comments that weren't addressed? + - Is the code properly formatted? + +4. **Documentation** + - Are inline comments clear where needed? + - Is the review document comprehensive? + - Are any new APIs documented? + +5. **PR Readiness** + - Is the branch up to date with main? + - Are commits atomic and well-described? + - Is the change diff reasonable in size? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... + +PR_SUMMARY: | + ## Summary + [2-3 sentences describing what this PR does] + + ## Key Changes + - [Change 1] + - [Change 2] + + ## Test Plan + - [How to test] +``` + +**Verdict meanings:** +- `APPROVE`: Ready to create PR +- `REQUEST_CHANGES`: Issues to fix before PR creation +- `COMMENT`: Minor items, can create PR but note feedback + +## Notes + +- This is the builder's final self-review before hand-off +- The PR_SUMMARY in your output can be used as the PR description +- Focus on "is this ready for someone else to review" not "is this perfect" +- Any issues found here are cheaper to fix than during integration review diff --git a/codev/protocols/bugfix/prompts/fix.md b/codev/protocols/bugfix/prompts/fix.md new file mode 100644 index 0000000..afecc33 --- /dev/null +++ b/codev/protocols/bugfix/prompts/fix.md @@ -0,0 +1,77 @@ +# FIX Phase Prompt + +You are executing the **FIX** phase of the BUGFIX protocol. + +## Your Goal + +Implement the bug fix and add a regression test. Keep it minimal and focused. + +## Context + +- **Issue**: #{{issue.number}} — {{issue.title}} +- **Current State**: {{current_state}} + +## Process + +### 1. Implement the Fix + +Apply the minimum change needed to resolve the bug: +- Fix the root cause identified in the INVESTIGATE phase +- Do NOT refactor surrounding code +- Do NOT add features beyond what's needed +- Do NOT fix other bugs you happen to notice (file separate issues) + +**Code Quality**: +- Self-documenting code (clear names, obvious structure) +- No commented-out code or debug prints +- Follow existing project conventions + +### 2. Add a Regression Test + +**A regression test is MANDATORY.** Every bugfix MUST include a test unless you provide explicit justification for why a test is impossible (e.g., pure CSS-only change with no testable behavior). If you skip the test, you MUST explain why in your commit message and PR description. + +Write a test that: +- Fails without the fix (demonstrates the bug) +- Passes with the fix (demonstrates the fix works) +- Covers the specific scenario from the issue +- Is deterministic (not flaky) + +Place tests following project conventions (`__tests__/`, `*.test.ts`, etc.). + +### 3. Verify the Fix + +Run build and tests: + +```bash +npm run build # Must pass +npm test # Must pass +``` + +Fix any failures before proceeding. If build/test commands don't exist, check `package.json`. + +### 4. Commit + +Stage and commit your changes: +- Use explicit file paths (never `git add -A` or `git add .`) +- Commit message: `Fix #{{issue.number}}: ` + +## Signals + +When fix and tests are complete and passing: + +``` +PHASE_COMPLETE +``` + +If you encounter a blocker: + +``` +BLOCKED:reason goes here +``` + +## Important Notes + +1. **Minimal changes only** — Fix the bug, nothing else +2. **Regression test is MANDATORY** — No fix without a test. If truly untestable, justify in writing. +3. **Build AND tests must pass** — Don't signal complete until both pass +4. **Stay under 300 LOC** — If the fix grows beyond this, signal `TOO_COMPLEX` diff --git a/codev/protocols/bugfix/prompts/investigate.md b/codev/protocols/bugfix/prompts/investigate.md new file mode 100644 index 0000000..ffa5438 --- /dev/null +++ b/codev/protocols/bugfix/prompts/investigate.md @@ -0,0 +1,77 @@ +# INVESTIGATE Phase Prompt + +You are executing the **INVESTIGATE** phase of the BUGFIX protocol. + +## Your Goal + +Understand the bug, reproduce it, identify the root cause, and assess whether it's fixable within BUGFIX scope (< 300 LOC). + +## Context + +- **Issue**: #{{issue.number}} — {{issue.title}} +- **Current State**: {{current_state}} + +## Process + +### 1. Read the Issue + +Read the full issue description. Identify: +- What is the expected behavior? +- What is the actual behavior? +- Are there reproduction steps? +- Are there error messages or screenshots? + +### 2. Reproduce the Bug + +Before fixing anything, confirm the bug exists: +- Follow the reproduction steps from the issue +- If no steps are given, infer them from the description +- Document the exact reproduction steps you used +- If you **cannot** reproduce, signal `BLOCKED` with details + +### 3. Identify Root Cause + +Trace the bug to its source: +- Read the relevant code paths +- Use grep/search to find related code +- Identify the exact file(s) and line(s) causing the issue +- Understand **why** the bug occurs, not just **where** + +### 4. Assess Complexity + +Determine if this is BUGFIX-appropriate: +- **< 300 LOC change**: Proceed with BUGFIX +- **> 300 LOC or architectural**: Signal `TOO_COMPLEX` to escalate + +Consider: +- How many files need to change? +- Does it require new abstractions or refactoring? +- Are there cascading effects? + +## Output + +By the end of this phase, you should know: +1. The exact root cause +2. Which files need to change +3. The approximate size of the fix +4. Whether it's BUGFIX-appropriate + +## Signals + +When investigation is complete: + +``` +PHASE_COMPLETE +``` + +If the bug is too complex for BUGFIX: + +``` +TOO_COMPLEX +``` + +If you're blocked (can't reproduce, missing context, etc.): + +``` +BLOCKED:reason goes here +``` diff --git a/codev/protocols/bugfix/prompts/pr.md b/codev/protocols/bugfix/prompts/pr.md new file mode 100644 index 0000000..fd28a79 --- /dev/null +++ b/codev/protocols/bugfix/prompts/pr.md @@ -0,0 +1,95 @@ +# PR Phase Prompt + +You are executing the **PR** phase of the BUGFIX protocol. + +## Your Goal + +Create a pull request, run CMAP review, and address feedback. + +## Context + +- **Issue**: #{{issue.number}} — {{issue.title}} +- **Current State**: {{current_state}} + +## Process + +### 1. Create the Pull Request + +Create a PR that links to the issue: + +```bash +gh pr create --title "Fix #{{issue.number}}: " --body "$(cat <<'EOF' +## Summary + +<1-2 sentence description of the bug and fix> + +Fixes #{{issue.number}} + +## Root Cause + + + +## Fix + + + +## Test Plan + +- [ ] Regression test added +- [ ] Build passes +- [ ] All tests pass +EOF +)" +``` + +### 2. Run CMAP Review + +Run 3-way parallel consultation on the PR: + +```bash +consult -m gemini --protocol bugfix --type pr & +consult -m codex --protocol bugfix --type pr & +consult -m claude --protocol bugfix --type pr & +``` + +All three should run in the background (`run_in_background: true`). + +### 3. Wait for Results and Address Feedback + +**DO NOT proceed to step 4 until ALL THREE consultations have returned results.** + +Wait for each background consultation to complete, then read the results: +- Use `TaskOutput` (with `block: true`) to retrieve each consultation result +- Record each model's verdict (APPROVE or REQUEST_CHANGES) +- Fix any issues identified by reviewers +- Push updates to the PR branch +- Re-run CMAP if substantial changes were made + +You must have three concrete verdicts (e.g., "gemini: APPROVE, codex: APPROVE, claude: APPROVE") before continuing. + +### 4. Notify Architect + +**DO NOT send this notification until you have all three CMAP verdicts from step 3.** + +Send a **single** notification that includes the PR link and each model's verdict: + +```bash +af send architect "PR # ready for review (fixes issue #{{issue.number}}). CMAP: gemini=, codex=, claude=" +``` + +**This is the only notification you send.** After this, your work is done — the architect +takes it from here (reviews, merges, cleans up). + +## Signals + +When PR is created and reviews are complete: + +``` +PHASE_COMPLETE +``` + +If you're blocked: + +``` +BLOCKED:reason goes here +``` diff --git a/codev/protocols/bugfix/protocol.json b/codev/protocols/bugfix/protocol.json new file mode 100644 index 0000000..d2b107a --- /dev/null +++ b/codev/protocols/bugfix/protocol.json @@ -0,0 +1,114 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "bugfix", + "version": "1.1.0", + "description": "Lightweight protocol for minor bugfixes using GitHub Issues", + "input": { + "type": "github-issue", + "required": false, + "default_for": ["--issue", "-i"] + }, + "hooks": { + "pre-spawn": { + "collision-check": true, + "comment-on-issue": "On it! Working on a fix now." + } + }, + "phases": [ + { + "id": "investigate", + "name": "Investigate", + "description": "Understand the bug and its root cause", + "type": "once", + "steps": [ + "read_issue", + "reproduce_bug", + "identify_root_cause", + "assess_complexity" + ], + "transition": { + "on_complete": "fix", + "on_too_complex": "escalate" + } + }, + { + "id": "fix", + "name": "Fix", + "description": "Implement the bug fix", + "type": "once", + "steps": [ + "implement_fix", + "add_tests", + "verify_fix", + "commit" + ], + "checks": { + "regression_test": { + "description": "A regression test MUST be added unless explicitly justified. No fix without a test.", + "required": true, + "skip_requires_justification": true + }, + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + }, + "tests": { + "command": "npm test", + "on_fail": "retry", + "max_retries": 2 + } + }, + "transition": { + "on_complete": "pr" + } + }, + { + "id": "pr", + "name": "Create PR", + "description": "Create pull request for the fix", + "type": "once", + "steps": [ + "create_pr", + "link_issue", + "request_review" + ], + "consultation": { + "on": "review", + "models": ["gemini", "codex"], + "type": "impl", + "parallel": true, + "max_rounds": 1 + }, + "transition": { + "on_complete": null + } + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current phase is complete", + "transitions_to": "next_phase" + }, + "TOO_COMPLEX": { + "description": "Bug is too complex for BUGFIX, escalate to SPIR", + "transitions_to": "escalate" + }, + "BLOCKED": { + "description": "Signal fix is blocked", + "requires": "reason" + } + }, + "defaults": { + "mode": "strict", + "consultation": { + "enabled": true, + "models": ["gemini", "codex"], + "parallel": true + }, + "checks": { + "build": "npm run build", + "test": "npm test" + } + } +} diff --git a/codev/protocols/experiment/builder-prompt.md b/codev/protocols/experiment/builder-prompt.md new file mode 100644 index 0000000..89a7870 --- /dev/null +++ b/codev/protocols/experiment/builder-prompt.md @@ -0,0 +1,61 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are executing a disciplined experiment. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the EXPERIMENT protocol yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Document your findings thoroughly +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +- **NEVER skip the 3-way review** — always follow porch next → porch done cycle +{{/if}} + +## Protocol +Follow the EXPERIMENT protocol: `codev/protocols/experiment/protocol.md` + +## EXPERIMENT Overview +The EXPERIMENT protocol ensures disciplined experimentation: + +1. **Hypothesis Phase**: Define what you're testing and success criteria +2. **Design Phase**: Plan the experiment approach +3. **Execute Phase**: Run the experiment and gather data +4. **Analyze Phase**: Evaluate results and draw conclusions + +{{#if task}} +## Experiment Focus +{{task_text}} +{{/if}} + +## Key Principles +- Start with a clear, falsifiable hypothesis +- Define success/failure criteria upfront +- Keep scope minimal for quick iteration +- Document findings regardless of outcome +- Separate experiment artifacts from production code + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the EXPERIMENT protocol document +2. Define your hypothesis clearly +3. Follow the phases in order diff --git a/codev/protocols/experiment/protocol.json b/codev/protocols/experiment/protocol.json new file mode 100644 index 0000000..ed04446 --- /dev/null +++ b/codev/protocols/experiment/protocol.json @@ -0,0 +1,101 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "experiment", + "version": "1.0.0", + "description": "Disciplined experimentation with hypothesis testing", + "input": { + "type": "none", + "required": false, + "default_for": [] + }, + "hooks": { + "pre-spawn": {} + }, + "phases": [ + { + "id": "hypothesis", + "name": "Hypothesis", + "description": "Define the hypothesis and success criteria", + "type": "once", + "steps": [ + "define_hypothesis", + "define_success_criteria", + "define_scope", + "create_experiment_doc" + ], + "transition": { + "on_complete": "design" + } + }, + { + "id": "design", + "name": "Design", + "description": "Design the experiment approach", + "type": "once", + "steps": [ + "choose_approach", + "identify_dependencies", + "plan_implementation", + "define_measurements" + ], + "transition": { + "on_complete": "execute" + } + }, + { + "id": "execute", + "name": "Execute", + "description": "Run the experiment", + "type": "once", + "steps": [ + "implement_prototype", + "gather_data", + "document_findings" + ], + "transition": { + "on_complete": "analyze" + } + }, + { + "id": "analyze", + "name": "Analyze", + "description": "Analyze results and draw conclusions", + "type": "once", + "steps": [ + "analyze_data", + "evaluate_hypothesis", + "document_conclusions", + "recommend_next_steps" + ], + "gate": { + "name": "experiment-complete", + "description": "Experiment complete", + "requires": ["conclusions_documented"], + "next": null + } + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current phase is complete", + "transitions_to": "next_phase" + }, + "BLOCKED": { + "description": "Signal experiment is blocked", + "requires": "reason" + }, + "HYPOTHESIS_REJECTED": { + "description": "Signal hypothesis was disproven", + "transitions_to": "analyze" + } + }, + "defaults": { + "mode": "soft", + "consultation": { + "enabled": false, + "models": [], + "parallel": false + }, + "checks": {} + } +} diff --git a/codev/protocols/experiment/protocol.md b/codev/protocols/experiment/protocol.md new file mode 100644 index 0000000..7bac432 --- /dev/null +++ b/codev/protocols/experiment/protocol.md @@ -0,0 +1,229 @@ +# EXPERIMENT Protocol + +## Overview + +Disciplined experimentation: Each experiment gets its own directory with `notes.md` tracking goals, code, and results. + +**Core Principle**: Document what you're trying, what you did, and what you learned. + +## When to Use + +**Use for**: Testing approaches, evaluating models, prototyping, proof-of-concept work, research spikes + +**Skip for**: Production code (use SPIR), simple one-off scripts, well-understood implementations (use TICK) + +## Structure + +``` +experiments/ +├── 1_descriptive_name/ +│ ├── notes.md # Goal, code, results +│ ├── experiment.py # Your experiment code +│ └── data/ +│ ├── input/ # Input data +│ └── output/ # Results, plots, etc. +└── 2_another_experiment/ + ├── notes.md + └── ... +``` + +## Workflow + +### 1. Create Experiment Directory + +```bash +# Create numbered directory +mkdir -p experiments/1_experiment_name +cd experiments/1_experiment_name + +# Initialize notes.md from template +cp codev/protocols/experiment/templates/notes.md notes.md +``` + +Or ask your AI assistant: "Create a new experiment for [goal]" + +### 2. Document the Goal + +Before writing code, clearly state what you're trying to learn in `notes.md`: + +```markdown +## Goal + +What specific question are you trying to answer? +What hypothesis are you testing? +``` + +### 3. Write Experiment Code + +- Keep it simple - experiments don't need production polish +- Reuse existing project modules where possible +- Any structure is fine - focus on learning, not architecture + +**Dependencies**: If your experiment requires libraries not in the main project: +1. Do NOT add them to the main project's `requirements.txt` or `pyproject.toml` +2. Create a `requirements.txt` inside your experiment folder +3. Document installation in `notes.md` + +### 4. Run and Observe + +Execute your experiment and capture results: +- Save output files to `data/output/` +- Take screenshots of visualizations +- Log key metrics + +### 5. Document Results + +Update `notes.md` with: +- What happened (actual results) +- What you learned (insights) +- What's next (follow-up actions) + +### 6. Commit + +```bash +git add experiments/1_experiment_name/ +git commit -m "[Experiment 1] Brief description of findings" +``` + +## notes.md Template + +See `templates/notes.md` for the full template. Key sections: + +```markdown +# Experiment ####: Name + +**Status**: In Progress | Complete | Disproved | Aborted + +**Date**: YYYY-MM-DD + +## Goal +What are you trying to learn? + +## Time Investment +Wall clock time vs active developer time + +## Code +- [experiment.py](experiment.py) - Brief description + +## Results +What happened? What did you learn? + +## Next Steps +What should be done based on findings? +``` + +## Best Practices + +### Keep It Simple +- Experiments don't need production polish +- Skip comprehensive error handling +- Focus on answering the question + +### Document Honestly +- Include failures - they're valuable learnings +- Note dead ends and why they didn't work +- Be specific about what surprised you + +### Track Time Investment +- Wall clock time: Total elapsed time +- Developer time: Active working time (excluding waiting) +- Helps estimate future similar work + +### Use Project Modules +- Don't duplicate existing code +- Import from your `src/` directory +- Experiments validate approaches, not reimplement them + +### Commit Progress +- Use `[Experiment ####]` commit prefix +- Commit intermediate results +- Include output files when reasonable + +## Integration with Other Protocols + +### Experiment → SPIR +When an experiment validates an approach for production use: + +1. Create a specification referencing the experiment +2. Link to experiment results as evidence +3. Use experiment code as reference implementation + +Example spec reference: +```markdown +## Background + +Experiment 5 validated that [approach] achieves [results]. +See: experiments/5_validation_test/notes.md +``` + +### Experiment → TICK +For small, validated changes discovered during experimentation: +- Use TICK for quick implementation +- Reference experiment as justification + +## Numbering Convention + +Use four-digit sequential numbering (consistent with project list): +- `1_`, `2_`, `3_`... +- Shared sequence across all experiments +- Descriptive name after the number (snake_case) + +Examples: +- `1_api_response_caching` +- `2_model_comparison` +- `3_performance_baseline` + +## Git Workflow + +### Commits +``` +[Experiment 1] Initial setup and goal +[Experiment 1] Add baseline measurements +[Experiment 1] Complete - caching improves latency 40% +``` + +### When to Commit +- After setting up the experiment +- After significant findings +- When completing the experiment + +**Data Management**: +- Include `data/output/` ONLY if files are small (summary metrics, small plots) +- Do NOT commit large datasets, binary model checkpoints, or heavy artifacts +- Add appropriate entries to `.gitignore` for large files +- Consider storing large outputs externally and linking in notes + +## Example Experiment + +``` +experiments/1_caching_strategy/ +├── notes.md +├── benchmark.py +├── cache_test.py +└── data/ + ├── input/ + │ └── sample_requests.json + └── output/ + ├── results.csv + └── latency_chart.png +``` + +**notes.md excerpt:** +```markdown +# Experiment 1: Caching Strategy Evaluation + +**Status**: Complete + +**Date**: 2024-01-15 + +## Goal +Determine if Redis caching improves API response times for repeated queries. + +## Results +- 40% latency reduction for cached queries +- Cache hit rate: 73% after warm-up +- Memory usage: 50MB for 10k cached responses + +## Next Steps +Create SPIR spec for production caching implementation. +``` diff --git a/codev/protocols/experiment/templates/notes.md b/codev/protocols/experiment/templates/notes.md new file mode 100644 index 0000000..18e1c63 --- /dev/null +++ b/codev/protocols/experiment/templates/notes.md @@ -0,0 +1,97 @@ +# Experiment ####: Name + +**Status**: In Progress | Complete | Disproved | Aborted + +**Date**: YYYY-MM-DD + +## Goal + +What are you trying to learn or test? Be specific about: +- The question you're answering +- The hypothesis you're testing +- Success criteria (how will you know if it worked?) + +## Effort + +**Approximate time spent**: [e.g., "4 hours"] + +*(Optional: Break down into setup, coding, analysis if helpful)* + +## Approach + +Brief description of the approach being tested: +- Key technique or method +- Why this approach was chosen +- Any alternatives considered + +## Environment & Reproduction + +**How to run**: +```bash +# Command to reproduce results +python experiment.py --input data/input/sample.json +``` + +**Dependencies** (if different from main project): +- List any additional packages required +- Or reference: `pip install -r requirements.txt` + +**Environment notes**: +- Python version, key library versions if relevant +- Any seeds or configuration needed for reproducibility + +## Code + +List your experiment files: +- [`experiment.py`](experiment.py) - Brief description +- [Other files as needed] + +## Results + +### Summary + +One-paragraph summary of key findings. + +### Key Findings + +1. **Finding one**: Description and significance +2. **Finding two**: Description and significance +3. **Finding three**: Description and significance + +### Metrics + +| Metric | Value | Notes | +|--------|-------|-------| +| Metric 1 | Value | Context | +| Metric 2 | Value | Context | + +### Output Files + +- `data/output/results.csv` - Raw results data +- `data/output/chart.png` - Visualization of findings + +## What Worked + +- List things that went well +- Approaches that proved effective +- Useful discoveries + +## What Didn't Work + +- Failed approaches (and why) +- Dead ends encountered +- Surprising obstacles + +## Next Steps + +Based on these findings: + +1. **Immediate**: What should happen right after this experiment? +2. **Follow-up experiments**: What new questions emerged? +3. **Production path**: If validated, what's needed for production? (SPIR spec?) + +## References + +- Links to relevant documentation +- Related experiments +- External resources consulted diff --git a/codev/protocols/maintain/builder-prompt.md b/codev/protocols/maintain/builder-prompt.md new file mode 100644 index 0000000..a33ca44 --- /dev/null +++ b/codev/protocols/maintain/builder-prompt.md @@ -0,0 +1,55 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are executing the MAINTAIN protocol to clean up and synchronize the codebase. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the MAINTAIN protocol yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Work through each phase methodically +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +- **NEVER skip the 3-way review** — always follow porch next → porch done cycle +{{/if}} + +## Protocol +Follow the MAINTAIN protocol: `codev/protocols/maintain/protocol.md` + +## MAINTAIN Overview +The MAINTAIN protocol handles codebase hygiene: + +1. **Audit Phase**: Scan for dead code, unused dependencies, stale docs +2. **Clean Phase**: Remove identified cruft, verify build +3. **Sync Phase**: Update documentation (arch.md, lessons-learned.md, CLAUDE.md) +4. **Verify Phase**: Run full test suite, confirm health + +## Key Rules +- Use soft deletion (move to `codev/maintain/.trash/`) +- Always verify build passes after removals +- Update documentation to match current architecture +- Don't remove anything actively used + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the MAINTAIN protocol document +2. Start with the Audit phase +3. Document all changes made diff --git a/codev/protocols/maintain/consult-types/impl-review.md b/codev/protocols/maintain/consult-types/impl-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/maintain/consult-types/impl-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/maintain/consult-types/pr-review.md b/codev/protocols/maintain/consult-types/pr-review.md new file mode 100644 index 0000000..048c23f --- /dev/null +++ b/codev/protocols/maintain/consult-types/pr-review.md @@ -0,0 +1,72 @@ +# PR Ready Review Prompt + +## Context +You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. + +## Focus Areas + +1. **Completeness** + - Are all spec requirements implemented? + - Are all plan phases complete? + - Is the review document written (`codev/reviews/XXXX-name.md`)? + - Are all commits properly formatted (`[Spec XXXX][Phase]`)? + +2. **Test Status** + - Do all tests pass? + - Is test coverage adequate for the changes? + - Are there any skipped or flaky tests? + +3. **Code Cleanliness** + - Is there any debug code left in? + - Are there any TODO comments that should be resolved? + - Are there any `// REVIEW:` comments that weren't addressed? + - Is the code properly formatted? + +4. **Documentation** + - Are inline comments clear where needed? + - Is the review document comprehensive? + - Are any new APIs documented? + +5. **PR Readiness** + - Is the branch up to date with main? + - Are commits atomic and well-described? + - Is the change diff reasonable in size? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... + +PR_SUMMARY: | + ## Summary + [2-3 sentences describing what this PR does] + + ## Key Changes + - [Change 1] + - [Change 2] + + ## Test Plan + - [How to test] +``` + +**Verdict meanings:** +- `APPROVE`: Ready to create PR +- `REQUEST_CHANGES`: Issues to fix before PR creation +- `COMMENT`: Minor items, can create PR but note feedback + +## Notes + +- This is the builder's final self-review before hand-off +- The PR_SUMMARY in your output can be used as the PR description +- Focus on "is this ready for someone else to review" not "is this perfect" +- Any issues found here are cheaper to fix than during integration review diff --git a/codev/protocols/maintain/prompts/audit.md b/codev/protocols/maintain/prompts/audit.md new file mode 100644 index 0000000..e637e9e --- /dev/null +++ b/codev/protocols/maintain/prompts/audit.md @@ -0,0 +1,111 @@ +# AUDIT Phase Prompt + +You are executing the **AUDIT** phase of the MAINTAIN protocol. + +## Your Goal + +Analyze the codebase to identify dead code, unused dependencies, and stale documentation. + +## Context + +- **Current State**: {{current_state}} + +## Process + +### 1. Determine Base Commit + +Find the last maintenance run: +```bash +ls codev/maintain/ +``` + +If previous runs exist, note the base commit to focus on changes since then. + +### 2. Scan for Dead Code + +Run static analysis tools: + +```bash +# TypeScript/JavaScript +npx ts-prune 2>/dev/null || echo "ts-prune not available" +npx depcheck 2>/dev/null || echo "depcheck not available" + +# Check for unused exports +grep -r "export " --include="*.ts" --include="*.tsx" | head -50 +``` + +### 3. Scan for Unused Dependencies + +Check package.json for unused dependencies: +```bash +cat package.json | grep -A100 '"dependencies"' | head -50 +``` + +Cross-reference with actual imports in the codebase. + +### 4. Scan for Stale Documentation + +Check for references to deleted files/functions: +```bash +# Recent changes +git log --oneline -20 + +# Check if arch.md references exist +grep -E "src/|packages/" codev/resources/arch.md | head -20 +``` + +### 5. Create Audit Report + +Create a maintenance run file: `codev/maintain/NNN.md` + +Document: +- Dead code identified (with file paths) +- Unused dependencies +- Stale documentation references +- Recommended actions + +Use the template structure: +```markdown +# Maintenance Run NNN + +**Date**: YYYY-MM-DD +**Base Commit**: + +## Dead Code Identified + +| File | Item | Reason | +|------|------|--------| +| path/to/file.ts | unusedFunction() | Not imported anywhere | + +## Unused Dependencies + +| Package | Reason | +|---------|--------| +| some-pkg | Not imported | + +## Stale Documentation + +| Document | Issue | +|----------|-------| +| arch.md | References deleted module | + +## Recommended Actions + +1. Remove X +2. Update Y +3. ... +``` + +## Signals + +When audit report is complete: + +``` +PHASE_COMPLETE +``` + +If blocked: + +``` +BLOCKED:reason +``` diff --git a/codev/protocols/maintain/prompts/clean.md b/codev/protocols/maintain/prompts/clean.md new file mode 100644 index 0000000..4596858 --- /dev/null +++ b/codev/protocols/maintain/prompts/clean.md @@ -0,0 +1,91 @@ +# CLEAN Phase Prompt + +You are executing the **CLEAN** phase of the MAINTAIN protocol. + +## Your Goal + +Remove the dead code and unused dependencies identified in the audit phase. + +## Context + +- **Current State**: {{current_state}} + +## Prerequisites + +Read the audit report from the previous phase: +```bash +ls -la codev/maintain/ +cat codev/maintain/*.md | tail -100 +``` + +## Process + +### 1. Remove Dead Code + +For each item identified in the audit: + +1. Verify it's truly unused (double-check with grep) +2. Use `git rm` for tracked files +3. For untracked files, move to `.trash/` before deleting + +**CRITICAL**: Use soft deletion first: +```bash +mkdir -p codev/maintain/.trash/$(date +%Y-%m-%d) +mv path/to/file codev/maintain/.trash/$(date +%Y-%m-%d)/ +``` + +### 2. Remove Unused Dependencies + +```bash +# Remove from package.json +npm uninstall +``` + +### 3. Verify Build After Each Removal + +After each significant removal: +```bash +npm run build +npm test -- --exclude='**/e2e/**' +``` + +If build fails, revert the change and investigate. + +### 4. Commit Changes + +Make atomic commits for each logical change: +```bash +git add +git commit -m "[Maintain] Remove unused X" +``` + +**NEVER use `git add -A` or `git add .`** + +## Important Rules + +1. **One removal at a time** - Don't batch unrelated changes +2. **Verify after each removal** - Build must pass +3. **Document what was removed** - Update the maintenance run file +4. **Soft delete first** - Move to .trash/ before permanent deletion +5. **Check for side effects** - Grep for references before removing + +## Output + +Update the maintenance run file with: +- What was removed +- Build/test status after removal +- Any issues encountered + +## Signals + +When all dead code is removed and build passes: + +``` +PHASE_COMPLETE +``` + +If blocked: + +``` +BLOCKED:reason +``` diff --git a/codev/protocols/maintain/prompts/sync.md b/codev/protocols/maintain/prompts/sync.md new file mode 100644 index 0000000..39953f7 --- /dev/null +++ b/codev/protocols/maintain/prompts/sync.md @@ -0,0 +1,113 @@ +# SYNC Phase Prompt + +You are executing the **SYNC** phase of the MAINTAIN protocol. + +## Your Goal + +Update documentation to match the current state of the codebase. + +## Context + +- **Current State**: {{current_state}} + +## Process + +### 1. Update arch.md + +Read the current architecture doc and compare with actual codebase: + +```bash +cat codev/resources/arch.md +ls -la packages/ src/ 2>/dev/null +``` + +Update: +- Directory structure (if changed) +- Component descriptions +- Key files and their purposes +- Remove references to deleted code +- Add new utilities/components + +**arch.md must explain HOW things work, not just WHAT they are.** + +### 2. Generate/Update lessons-learned.md + +Scan review documents for lessons: + +```bash +ls codev/reviews/ +``` + +Extract actionable lessons: +- Testing practices +- Architecture decisions +- Process improvements +- Patterns to follow/avoid + +Format: +```markdown +## [Topic] +- [From NNN] Lesson description +``` + +### 3. Sync CLAUDE.md with AGENTS.md + +Compare the two files: +```bash +diff CLAUDE.md AGENTS.md | head -50 +``` + +They must be identical. Update the stale one to match. + +### 4. Prune Documentation + +Check document sizes: +```bash +wc -l CLAUDE.md AGENTS.md README.md +``` + +Target ~400 lines for CLAUDE.md/README.md (guideline, not mandate). + +For any content removed, document: +- WHAT was removed +- WHY it was removed (OBSOLETE, DUPLICATIVE, MOVED, VERBOSE) +- WHERE it moved (if applicable) + +### 5. Commit Documentation Changes + +```bash +git add codev/resources/arch.md codev/resources/lessons-learned.md +git commit -m "[Maintain] Update arch.md and lessons-learned.md" + +git add CLAUDE.md AGENTS.md +git commit -m "[Maintain] Sync CLAUDE.md with AGENTS.md" +``` + +## Important Rules + +1. **Never invent structure** - Only document what exists +2. **Verify file paths** - Check that referenced files exist +3. **Keep it current** - Remove obsolete references +4. **Preserve important content** - Don't delete patterns/best practices +5. **Document deletions** - Every removal needs justification + +## Output + +Update the maintenance run file with: +- Documents updated +- What was added/removed/changed +- Any issues encountered + +## Signals + +When documentation is synchronized: + +``` +PHASE_COMPLETE +``` + +If blocked: + +``` +BLOCKED:reason +``` diff --git a/codev/protocols/maintain/prompts/verify.md b/codev/protocols/maintain/prompts/verify.md new file mode 100644 index 0000000..020c66a --- /dev/null +++ b/codev/protocols/maintain/prompts/verify.md @@ -0,0 +1,110 @@ +# VERIFY Phase Prompt + +You are executing the **VERIFY** phase of the MAINTAIN protocol. + +## Your Goal + +Run final validation and prepare for PR creation. + +## Context + +- **Current State**: {{current_state}} + +## Process + +### 1. Run Full Test Suite + +```bash +npm run build +npm test +``` + +Both must pass. If either fails, go back and fix the issue. + +### 2. Run Linting + +```bash +npm run lint 2>/dev/null || echo "No lint script" +``` + +Fix any linting errors. + +### 3. Verify Documentation Links + +Check that documentation references resolve: +```bash +# Check arch.md file references +grep -oE 'src/[^ ]+|packages/[^ ]+' codev/resources/arch.md | while read f; do + [ -e "$f" ] || echo "Missing: $f" +done +``` + +### 4. Update Maintenance Run Summary + +Finalize the maintenance run file with: + +```markdown +## Summary + +- **Dead code removed**: X files, Y functions +- **Dependencies removed**: Z packages +- **Documentation updated**: arch.md, lessons-learned.md +- **All tests passing**: Yes/No +- **Build status**: Success/Failure + +## Next Maintenance + +Recommended focus areas for next run: +- ... +``` + +### 5. Create PR + +```bash +git push origin HEAD + +gh pr create --title "[Maintain] Codebase maintenance run NNN" --body "$(cat <<'EOF' +## Summary + +- Dead code removal +- Documentation sync +- Dependency cleanup + +## Changes + +[List key changes] + +## Verification + +- [x] Build passes +- [x] Tests pass +- [x] Documentation updated +EOF +)" +``` + +## Validation Checklist + +Before signaling complete: + +- [ ] All tests pass +- [ ] Build succeeds +- [ ] No import/module errors +- [ ] Documentation links resolve +- [ ] Linter passes (if configured) +- [ ] Maintenance run file is complete +- [ ] PR is created + +## Signals + +When validation passes and PR is ready: + +``` +PHASE_COMPLETE +``` + +If blocked: + +``` +BLOCKED:reason +``` diff --git a/codev/protocols/maintain/protocol.json b/codev/protocols/maintain/protocol.json new file mode 100644 index 0000000..d6d11b1 --- /dev/null +++ b/codev/protocols/maintain/protocol.json @@ -0,0 +1,141 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "maintain", + "alias": "maint", + "version": "2.0.0", + "description": "Codebase maintenance - dead code removal, doc sync, hygiene with 3-way review", + "input": { + "type": "protocol", + "required": false, + "default_for": ["--protocol maintain"] + }, + "phases": [ + { + "id": "audit", + "name": "Audit", + "description": "Analyze codebase for dead code, unused dependencies, stale docs", + "type": "build_verify", + "build": { + "prompt": "audit.md", + "artifact": "codev/maintain/*.md" + }, + "verify": { + "type": "impl", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 3, + "on_complete": { + "commit": true, + "push": true + }, + "next": "clean" + }, + { + "id": "clean", + "name": "Clean", + "description": "Remove identified dead code and unused dependencies", + "type": "build_verify", + "build": { + "prompt": "clean.md", + "artifact": "src/**/*.{ts,tsx,js,jsx}" + }, + "verify": { + "type": "impl", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 5, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + }, + "tests": { + "command": "npm test -- --exclude='**/e2e/**'", + "on_fail": "retry", + "max_retries": 2 + } + }, + "next": "sync" + }, + { + "id": "sync", + "name": "Sync Documentation", + "description": "Update documentation to match current codebase", + "type": "build_verify", + "build": { + "prompt": "sync.md", + "artifact": "codev/resources/*.md" + }, + "verify": { + "type": "impl", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 5, + "on_complete": { + "commit": true, + "push": true + }, + "next": "verify" + }, + { + "id": "verify", + "name": "Verify", + "description": "Final validation and PR creation", + "type": "build_verify", + "build": { + "prompt": "verify.md", + "artifact": "codev/maintain/*.md" + }, + "verify": { + "type": "pr", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 3, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + }, + "tests": { + "command": "npm test", + "on_fail": "retry", + "max_retries": 2 + } + }, + "gate": "maintain-complete", + "next": null + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current phase is complete", + "transitions_to": "verify" + }, + "BLOCKED": { + "description": "Signal maintenance is blocked", + "requires": "reason" + } + }, + "defaults": { + "mode": "strict", + "max_iterations": 5, + "verify": { + "models": ["gemini", "codex", "claude"], + "parallel": true + } + } +} diff --git a/codev/protocols/maintain/protocol.md b/codev/protocols/maintain/protocol.md new file mode 100644 index 0000000..b47ffc1 --- /dev/null +++ b/codev/protocols/maintain/protocol.md @@ -0,0 +1,507 @@ +# MAINTAIN Protocol + +## Overview + +MAINTAIN is a periodic maintenance protocol for keeping codebases healthy. It runs as a **strict porch protocol** with sequential phases and 3-way consultation (Gemini, Codex, Claude) at each phase. + +**Core Principle**: Regular maintenance prevents technical debt accumulation. + +**Key Documents**: MAINTAIN is responsible for keeping these living documents accurate and consistent: +- `codev/resources/arch.md` - Architecture documentation (how the system works) +- `codev/resources/lessons-learned.md` - Extracted wisdom from reviews + +Any builder can update these files during development, but MAINTAIN ensures they stay consistent with the actual codebase. + +## When to Use MAINTAIN + +- When the user/architect requests it +- Before a release (clean slate for shipping) +- Quarterly maintenance window +- After completing a major feature +- When the codebase feels "crusty" + +## Execution Model + +MAINTAIN is orchestrated by porch with 4 sequential phases: + +``` +af spawn --protocol maintain + ↓ +1. AUDIT: Scan for dead code, unused deps, stale docs + ↓ (3-way review) +2. CLEAN: Remove identified cruft + ↓ (3-way review + build/test checks) +3. SYNC: Update documentation + ↓ (3-way review) +4. VERIFY: Final validation + PR + ↓ (3-way review) +PR with maintenance changes + ↓ +Architect reviews → Merge +``` + +Each phase goes through build-verify cycles with 3-way consultation before proceeding. + +## Prerequisites + +Before starting MAINTAIN: +1. Check `codev/maintain/` for last maintenance run +2. Note the base commit from that run +3. Focus on changes since that commit: `git log --oneline ..HEAD` + +--- + +## Maintenance Files + +Each maintenance run creates a numbered file in `codev/maintain/`: + +``` +codev/maintain/ +├── 1.md +├── 2.md +└── ... +``` + +**Template**: `codev/protocols/maintain/templates/maintenance-run.md` + +The file records: +- Base commit (starting point) +- Tasks completed +- Findings and deferred items +- Summary + +--- + +## Task List + +### Code Hygiene Tasks + +| Task | Parallelizable | Human Review? | Description | +|------|----------------|---------------|-------------| +| Remove dead code | Yes | No | Delete unused functions, imports, unreachable code | +| Remove unused dependencies | Yes | Yes | Check package.json/requirements.txt for unused packages | +| Clean unused flags | Yes | No | Remove feature flags that are always on/off | +| Fix flaky tests | No | Yes | Investigate and fix intermittently failing tests | +| Update outdated dependencies | Yes | Yes | Bump dependencies with breaking change review | +| Identify duplicate code | Yes | Yes | Find repeated patterns that should be utility functions | + +**Tools**: +```bash +# TypeScript/JavaScript +npx ts-prune # Find unused exports +npx depcheck # Find unused dependencies +npx jscpd . # Find copy-paste code (optional) + +# Python +ruff check --select F401 # Find unused imports +``` + +### Documentation Sync Tasks + +| Task | Parallelizable | Human Review? | Description | +|------|----------------|---------------|-------------| +| Update arch.md | Yes | No | Sync architecture doc with actual codebase | +| Generate lessons-learned.md | Yes | Yes | Extract wisdom from review documents | +| Sync CLAUDE.md ↔ AGENTS.md | Yes | No | Ensure both files match | +| Prune documentation | Yes | Yes | Remove obsolete info, keep CLAUDE.md/README.md under 400 lines | +| Check spec/plan/review consistency | Yes | Yes | Find specs without reviews, plans that don't match code | +| Remove stale doc references | Yes | No | Delete references to deleted code/files | + +### Project Tracking Tasks + +| Task | Parallelizable | Human Review? | Description | +|------|----------------|---------------|-------------| +| Update GitHub Issue statuses | Yes | No | Close completed issues, update labels | + +### Framework Tasks + +| Task | Parallelizable | Human Review? | Description | +|------|----------------|---------------|-------------| +| Run codev update | No | Yes | Update codev framework to latest version | + +--- + +## Task Details + +### Update arch.md + +Scan the actual codebase and update `codev/resources/arch.md`: + +**Discovery phase**: +1. `git log --oneline ..HEAD` - what changed since last maintenance +2. `ls -R` key directories to find new files/modules +3. `grep` for new exports, classes, key functions +4. Review new/modified specs: `git diff ..HEAD --name-only -- codev/specs/` +5. Review new/modified plans: `git diff ..HEAD --name-only -- codev/plans/` + +**Update arch.md**: +1. Verify directory structure matches documented structure +2. Update component descriptions for changed modules +3. Add new utilities/helpers discovered +4. Remove references to deleted code +5. Update technology stack if dependencies changed +6. Document new integration points or APIs +7. Capture architectural decisions from new specs/plans + +**Primary sources** (specs/plans): +- Architectural decisions from specs +- Component relationships from plans +- Design rationale and tradeoffs + +**Secondary sources** (code): +- File locations and their purpose +- Key functions/classes and what they do +- Data flow and dependencies +- Configuration options +- CLI commands and flags + +**What NOT to include**: +- Implementation details that change frequently +- Line numbers (they go stale) +- Full API documentation (use JSDoc/docstrings for that) + +**Primary Purpose**: arch.md should enable a developer (or AI agent) to rapidly understand the entire system - not just file locations, but **how things actually work**. + +**Recommended Document Structure**: +```markdown +# Project Architecture + +## Overview +[High-level description: what the system does, core design philosophy, 2-3 sentences] + +## Quick Start for Developers +[The fastest path to understanding: "To understand X, read Y first"] + +## Technology Stack +[Technologies, frameworks, key dependencies with versions] + +## Directory Structure +[Complete directory tree with explanations for each major directory] + +## Major Components + +### [Component Name] (e.g., Agent Farm) +- **Purpose**: What problem it solves +- **Location**: path/to/component +- **How It Works**: + - Step-by-step explanation of the mechanism + - Key technologies used (e.g., "uses shellper processes for terminal persistence") + - Runtime behavior (e.g., "spawns a shellper process per builder terminal") + - State management (e.g., "state stored in SQLite at .agent-farm/state.db") +- **Key Files**: + - `file.ts` - does X + - `other.ts` - handles Y +- **Configuration**: How to customize behavior +- **Common Operations**: Examples of typical usage + +[Repeat for each major component - be thorough about HOW, not just WHAT] + +## Utility Functions & Helpers +### [Utility Category] +- **File**: path/to/utility.ts +- **Functions**: `functionName()` - Description and use case +- **When to Use**: Guidance on appropriate usage + +## Data Flow +[How data moves through the system, with concrete examples] + +## Key Design Decisions +[Important architectural choices and their rationale - the WHY] + +## Integration Points +[External services, APIs, databases, and how they connect] + +## Development Patterns +[Common patterns used throughout the codebase] +``` + +**Critical: The "How It Works" Requirement** + +For each major component, arch.md MUST explain the implementation mechanism, not just the purpose. Examples of good vs bad: + +| Bad (just WHAT) | Good (includes HOW) | +|-----------------|---------------------| +| "Agent Farm manages builders" | "Agent Farm spawns builders in isolated git worktrees. Each builder runs in a shellper-backed terminal session. The Tower dashboard exposes terminals via WebSocket. State is persisted in SQLite." | +| "Consult tool queries AI models" | "Consult shells out to external CLIs (gemini-cli, codex, claude). It writes the consultant role to a temp file, sets environment variables, and streams stdout/stderr back to the user." | + +This level of detail enables rapid onboarding and debugging. + +**Content Quality Standards**: +- **Be Specific**: Include exact file paths, actual function names, concrete examples +- **Maintain Accuracy**: Cross-reference specs/plans with actual implementation; flag discrepancies +- **Optimize for Quick Understanding**: Use clear hierarchy, highlight commonly used components +- **Stay Current**: Reflect actual state, not aspirational; remove deprecated components + +**Special Attention Areas**: + +1. **Utility Functions** (critical for productivity): + - Document every utility function with exact location + - Explain what each does and when to use it + - Include parameter types and return types + +2. **Directory Structure** (often first thing referenced): + - Keep directory tree up-to-date and complete + - Explain purpose of each major directory + - Highlight where specific types of files should be placed + +3. **Integration Points** (critical for understanding system boundaries): + - Document all external dependencies and APIs + - Explain how different parts connect + - Note special configuration requirements + +**Quality Assurance Before Finalizing**: +- [ ] All file paths are correct and current +- [ ] All documented functions actually exist +- [ ] Directory structure matches reality +- [ ] Architectural decisions are accurately represented +- [ ] Document is internally consistent + +**Constraints**: +- Never invent structure - only document what exists or is in specs/plans +- Never make architectural decisions - document them, don't make them +- Always verify documentation against actual implementation + +### Generate lessons-learned.md + +Extract actionable wisdom from review documents into `codev/resources/lessons-learned.md`: + +**Discovery phase**: +1. Find new/modified reviews: `git diff ..HEAD --name-only -- codev/reviews/` +2. Read each new/modified review file + +**Extract from reviews**: +1. Read all files in `codev/reviews/` +2. Extract lessons that are: + - Actionable (not just "we learned X") + - Durable (still relevant) + - General (applicable beyond one project) +3. Organize by topic (Testing, Architecture, Process, etc.) +4. Link back to source review +5. Prune outdated lessons + +**Template**: +```markdown +# Lessons Learned + +## Testing +- [From 1] Always use XDG sandboxing in tests to avoid touching real $HOME +- [From 9] Verify dependencies actually export what you expect + +## Architecture +- [From 8] Single source of truth beats distributed state +- [From 31] SQLite with WAL mode handles concurrency better than JSON files + +## Process +- [From 1] Multi-agent consultation catches issues humans miss +``` + +### Sync CLAUDE.md ↔ AGENTS.md + +Ensure both instruction files contain the same content: + +1. Diff the two files +2. Identify divergence +3. Update the stale one to match +4. Both should be identical (per AGENTS.md standard) + +### Prune Documentation + +**CRITICAL: Documentation pruning requires JUSTIFICATION for every deletion.** + +Size targets (~400 lines for CLAUDE.md/README.md) are **guidelines, not mandates**. Never sacrifice clarity or important content just to hit a line count. + +**Before deleting ANY content, document:** +1. **What** is being removed (quote or summarize) +2. **Why** it's being removed: + - `OBSOLETE` - References deleted code/features + - `DUPLICATIVE` - Same info exists elsewhere (cite location) + - `MOVED` - Relocated to another file (cite new location) + - `VERBOSE` - Can be condensed without losing meaning +3. **Decision** - Delete, move, or keep with note + +**Create a deletion log in your maintenance file:** +```markdown +## Documentation Changes + +### arch.md +| Section | Action | Reason | +|---------|--------|--------| +| "Old API docs" | DELETED | OBSOLETE - API removed in v1.2 | +| "Installation" | MOVED | To INSTALL.md for brevity | +| "Architecture patterns" | KEPT | Still relevant, referenced by builders | +``` + +**Files to review**: +- `codev/resources/arch.md` - remove references to deleted code/modules +- `codev/resources/lessons-learned.md` - remove outdated lessons +- `CLAUDE.md` / `AGENTS.md` - target ~400 lines (guideline, not hard limit) +- `README.md` - target ~400 lines (guideline, not hard limit) + +**Conservative approach**: +- When in doubt, KEEP the content +- If unsure, ASK the architect before deleting +- Prefer MOVING over DELETING +- Never delete "development patterns" or "best practices" sections without explicit approval + +**What to extract (move, don't delete)**: +- Detailed command references → `codev/resources/commands/` +- Protocol details → `codev/protocols/*/protocol.md` +- Tool configuration → `codev/resources/` + +**What to ALWAYS keep in CLAUDE.md**: +- Git prohibitions and safety rules +- Critical workflow instructions +- Protocol selection guidance +- Consultation requirements +- Links to detailed docs + +**Good candidates for deletion from CLAUDE.md**: +- Content duplicated elsewhere (e.g., in protocol files, role files, docs/) +- **When removing duplicated content**: Replace with a pointer to the canonical location + ```markdown + ## Consult Tool + + See `codev/resources/commands/consult.md` for full documentation. + ``` +- This keeps CLAUDE.md as an index/guide rather than duplicating detailed docs + +### Remove Dead Code + +Use static analysis to find and remove unused code: + +1. Run analysis tools (ts-prune, depcheck, ruff) +2. Review findings for false positives +3. Use `git rm` to remove confirmed dead code +4. Commit with descriptive message + +**Important**: Use `git rm`, not `rm`. Git history preserves deleted files. + +### Update Dependencies + +Review and update outdated dependencies: + +1. Run `npm outdated` or equivalent +2. Categorize updates: + - Patch: Safe to auto-update + - Minor: Review changelog + - Major: Requires human review for breaking changes +3. Update and test +4. Document any migration steps + +### Run codev update + +Update the codev framework to the latest version: + +```bash +codev update +``` + +This updates protocols, templates, and agents while preserving your specs, plans, and reviews. + +--- + +## Validation + +After completing tasks, validate the codebase: + +- [ ] All tests pass +- [ ] Build succeeds +- [ ] No import/module errors +- [ ] Documentation links resolve +- [ ] Linter passes + +If validation fails, investigate and fix before creating PR. + +--- + +## 3-Way Review (Before PR) + +After completing all tasks and validation, run a 3-way consultation review: + +```bash +# Run all three in parallel +consult -m gemini --protocol maintain --type pr & +consult -m codex --protocol maintain --type pr & +consult -m claude --protocol maintain --type pr & +wait +``` + +**Focus areas for maintenance review:** +- Are deletions justified and documented? +- Is arch.md accurate and complete? +- Are lessons-learned.md entries actionable? +- Any regressions or side effects? + +**Verdicts:** +- All APPROVE → Create PR +- Any REQUEST_CHANGES → Address feedback, re-run review +- Conflicting opinions → Use judgment, document decision + +Only create the PR after the 3-way review passes. + +--- + +## Rollback Strategy + +### For code changes +```bash +# Git history preserves everything +git log --all --full-history -- path/to/file +git checkout ~1 -- path/to/file +``` + +### For untracked files +Move to `codev/maintain/.trash/YYYY-MM-DD/` before deleting. Retained for 30 days. + +--- + +## Commit Messages + +``` +[Maintain] Remove 5 unused exports +[Maintain] Update arch.md with new utilities +[Maintain] Generate lessons-learned.md +[Maintain] Sync CLAUDE.md with AGENTS.md +[Maintain] Update dependencies (patch) +``` + +--- + +## Governance + +MAINTAIN is an **operational protocol**, not a feature development protocol: + +| Document | Required? | +|----------|-----------| +| Spec | No | +| Plan | No | +| Review | No | +| 3-Way Consultation | **Yes** (before creating PR) | + +**Exception**: If MAINTAIN reveals need for architectural changes, those should follow SPIR. + +--- + +## Best Practices + +1. **Don't be aggressive**: When in doubt, KEEP the content. It's easier to delete later than to recover lost knowledge. +2. **Check git blame**: Understand why code/docs exist before removing +3. **Run full test suite**: Not just affected tests +4. **Group related changes**: One commit per logical change +5. **Document EVERY deletion**: Include what, why, and where (if moved) +6. **Ask when unsure**: Consult architect before removing "important-looking" content +7. **Prefer moving over deleting**: Extract to another file rather than removing entirely +8. **Size targets are guidelines**: Never sacrifice clarity to hit a line count + +--- + +## Anti-Patterns + +1. **Aggressive rewriting without explanation**: "I condensed it" is not a reason +2. **Deleting without documenting why**: Every deletion needs justification in the maintenance file +3. **Hitting line count targets at all costs**: 400 lines is a guideline, not a mandate +4. **Removing "patterns" or "best practices" sections**: These are high-value content +5. **Deleting everything the audit finds**: Review each item individually +6. **Skipping validation**: "It looked dead/obsolete" is not validation +7. **Using `rm` instead of `git rm`**: Lose history +8. **Making changes the architect can't review**: Big deletions need clear explanations diff --git a/codev/protocols/maintain/templates/maintenance-run.md b/codev/protocols/maintain/templates/maintenance-run.md new file mode 100644 index 0000000..81268b3 --- /dev/null +++ b/codev/protocols/maintain/templates/maintenance-run.md @@ -0,0 +1,64 @@ +# Maintenance Run NNN + +## Metadata +- **Date**: YYYY-MM-DD +- **Base Commit**: (commit hash at start) +- **PR**: #NNN +- **Scope**: full | code-only | docs-only + +## Changes Since Last Run + + + +``` +git log --oneline ..HEAD +``` + +## Tasks Completed + +### Code Hygiene +- [ ] Dead code removal +- [ ] Unused dependencies +- [ ] Dependency updates +- [ ] Test maintenance + +### Documentation +- [ ] arch.md sync +- [ ] lessons-learned.md generation +- [ ] CLAUDE.md / AGENTS.md sync +- [ ] Documentation pruning (obsolete content, size limits) + +### Framework +- [ ] codev update +- [ ] GitHub Issue status updates (close completed, update labels) + +## Findings + + + +## Documentation Changes + + + +### arch.md +| Section | Action | Reason | +|---------|--------|--------| +| (example) | KEPT/MOVED/DELETED | (justification) | + +### CLAUDE.md +| Section | Action | Reason | +|---------|--------|--------| +| (example) | KEPT/MOVED/DELETED | (justification) | + +### README.md +| Section | Action | Reason | +|---------|--------|--------| +| (example) | KEPT/MOVED/DELETED | (justification) | + +## Deferred + + + +## Summary + + diff --git a/codev/protocols/protocol-schema.json b/codev/protocols/protocol-schema.json new file mode 100644 index 0000000..375108b --- /dev/null +++ b/codev/protocols/protocol-schema.json @@ -0,0 +1,290 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://codev.dev/protocol-schema.json", + "title": "Protocol Definition", + "description": "Schema for porch protocol definitions", + "type": "object", + "required": ["name", "version", "description", "phases"], + "properties": { + "name": { + "type": "string", + "description": "Protocol identifier (e.g., 'spir', 'tick', 'bugfix')" + }, + "version": { + "type": "string", + "pattern": "^\\d+\\.\\d+\\.\\d+$", + "description": "Semantic version of the protocol" + }, + "description": { + "type": "string", + "description": "Human-readable description of the protocol" + }, + "phases": { + "type": "array", + "description": "Ordered list of protocol phases", + "items": { + "$ref": "#/definitions/phase" + }, + "minItems": 1 + }, + "input": { + "$ref": "#/definitions/protocolInput" + }, + "hooks": { + "$ref": "#/definitions/protocolHooks" + }, + "signals": { + "type": "object", + "description": "Signal definitions for state transitions", + "additionalProperties": { + "$ref": "#/definitions/signal" + } + }, + "defaults": { + "type": "object", + "description": "Default configuration for the protocol", + "properties": { + "mode": { + "type": "string", + "enum": ["strict", "soft"], + "description": "Default orchestration mode for the protocol" + }, + "consultation": { + "$ref": "#/definitions/consultationDefaults" + }, + "checks": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + }, + "definitions": { + "phase": { + "type": "object", + "required": ["id", "name", "type"], + "properties": { + "id": { + "type": "string", + "description": "Unique phase identifier" + }, + "name": { + "type": "string", + "description": "Human-readable phase name" + }, + "description": { + "type": "string", + "description": "Phase description" + }, + "type": { + "type": "string", + "enum": ["once", "per_plan_phase"], + "description": "Whether phase runs once or per plan phase" + }, + "steps": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Ordered list of steps within the phase" + }, + "checks": { + "type": "object", + "description": "Build/test checks for this phase", + "additionalProperties": { + "$ref": "#/definitions/check" + } + }, + "consultation": { + "$ref": "#/definitions/consultation" + }, + "gate": { + "$ref": "#/definitions/gate" + }, + "transition": { + "$ref": "#/definitions/transition" + } + } + }, + "check": { + "type": "object", + "required": ["command"], + "properties": { + "command": { + "type": "string", + "description": "Command to run" + }, + "on_fail": { + "type": "string", + "description": "Action on failure: 'retry' or phase name to return to" + }, + "max_retries": { + "type": "integer", + "minimum": 0, + "description": "Maximum retry attempts" + }, + "retry_delay": { + "type": "integer", + "minimum": 0, + "description": "Delay between retries in seconds" + } + } + }, + "consultation": { + "type": "object", + "properties": { + "on": { + "type": "string", + "enum": ["review", "complete"], + "description": "When to trigger consultation" + }, + "models": { + "type": "array", + "items": { + "type": "string" + }, + "description": "AI models to consult" + }, + "type": { + "type": "string", + "description": "Review type (spec, plan, impl, pr, phase, integration)" + }, + "parallel": { + "type": "boolean", + "description": "Run consultations in parallel" + }, + "max_rounds": { + "type": "integer", + "minimum": 1, + "description": "Maximum revision rounds" + }, + "next": { + "type": "string", + "description": "Phase to proceed to after consultation" + } + } + }, + "consultationDefaults": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether consultation is enabled by default" + }, + "models": { + "type": "array", + "items": { + "type": "string" + } + }, + "parallel": { + "type": "boolean" + } + } + }, + "gate": { + "type": "object", + "required": ["name"], + "properties": { + "name": { + "type": "string", + "description": "Gate identifier" + }, + "description": { + "type": "string", + "description": "What this gate checks" + }, + "requires": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Items that must be complete to pass" + }, + "next": { + "type": ["string", "null"], + "description": "Next phase after gate (null for terminal)" + } + } + }, + "transition": { + "type": "object", + "properties": { + "on_complete": { + "type": "string", + "description": "Phase to transition to on completion" + }, + "on_fail": { + "type": "string", + "description": "Phase to return to on failure" + }, + "on_too_complex": { + "type": "string", + "description": "Action when task is too complex" + }, + "on_all_phases_complete": { + "type": "string", + "description": "Phase to transition to when all plan phases are done" + } + } + }, + "signal": { + "type": "object", + "properties": { + "description": { + "type": "string" + }, + "transitions_to": { + "type": "string" + }, + "requires": { + "type": "string" + } + } + }, + "protocolInput": { + "type": "object", + "description": "Protocol input configuration - defines what input types a protocol accepts", + "properties": { + "type": { + "type": "string", + "enum": ["spec", "github-issue", "task", "protocol", "shell", "worktree"], + "description": "Primary input type for this protocol" + }, + "required": { + "type": "boolean", + "description": "Whether an input of this type is required" + }, + "default_for": { + "type": "array", + "items": { + "type": "string" + }, + "description": "CLI flags this protocol is the default for (e.g., ['--issue', '-i'])" + } + } + }, + "protocolHooks": { + "type": "object", + "description": "Hooks triggered at various points in the spawn lifecycle", + "properties": { + "pre-spawn": { + "type": "object", + "description": "Hooks executed before spawning the builder", + "properties": { + "collision-check": { + "type": "boolean", + "description": "Check for worktree/PR collisions before spawning" + }, + "comment-on-issue": { + "type": "string", + "description": "Comment to post on GitHub issue when spawning" + } + } + } + } + } + } +} diff --git a/codev/protocols/spike/builder-prompt.md b/codev/protocols/spike/builder-prompt.md new file mode 100644 index 0000000..4bf2faf --- /dev/null +++ b/codev/protocols/spike/builder-prompt.md @@ -0,0 +1,62 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are executing a time-boxed technical feasibility spike. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the SPIKE protocol yourself (no porch orchestration) +- Stay focused on the question — don't gold-plate +- The findings document is your deliverable, not the code +{{/if}} + +## Protocol +Follow the SPIKE protocol: `codev/protocols/spike/protocol.md` + +{{#if task}} +## Spike Question +{{task_text}} +{{/if}} + +## Recommended Workflow + +Follow this 3-step workflow. You can skip or reorder steps as the investigation demands. + +### 1. Research +- Read documentation, examine existing code, search for prior art +- Identify constraints, dependencies, and potential blockers +- Understand the problem space before writing any code + +### 2. Iterate +- Build minimal proof-of-concept code to test approaches +- Focus on answering the feasibility question, not building production code +- POC code doesn't need tests or polish +- **Skip this step** if the answer is clear from research alone + +### 3. Findings +- Write findings to `codev/spikes/-.md` using the template +- Provide a clear feasibility verdict: Feasible / Not Feasible / Feasible with Caveats +- Commit the findings document +- Notify the architect: `af send architect "Spike complete. Verdict: [verdict]"` + +## Key Principles + +- **Time-boxing**: Stay focused on the question. Don't explore tangents. +- **Exploration over perfection**: POC code doesn't need tests or polish. +- **Clear output**: The findings document is the deliverable, not the code. +- **Know when to stop**: Once you can answer the feasibility question, write findings and stop. Don't keep iterating. +- **Document failures**: "Not feasible" is a valid and valuable finding. + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your findings under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the SPIKE protocol document +2. Understand the question you're investigating +3. Start with research — don't jump straight to code diff --git a/codev/protocols/spike/protocol.json b/codev/protocols/spike/protocol.json new file mode 100644 index 0000000..9db384b --- /dev/null +++ b/codev/protocols/spike/protocol.json @@ -0,0 +1,36 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "spike", + "version": "1.0.0", + "description": "Time-boxed technical feasibility exploration", + "input": { + "type": "task", + "required": false, + "default_for": [] + }, + "phases": [ + { + "id": "spike", + "name": "Spike", + "description": "Execute the spike — research, iterate, write findings", + "type": "once" + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal spike is complete" + }, + "BLOCKED": { + "description": "Signal spike is blocked", + "requires": "reason" + } + }, + "defaults": { + "mode": "soft", + "consultation": { + "enabled": false, + "models": [], + "parallel": false + } + } +} diff --git a/codev/protocols/spike/protocol.md b/codev/protocols/spike/protocol.md new file mode 100644 index 0000000..8a07a1d --- /dev/null +++ b/codev/protocols/spike/protocol.md @@ -0,0 +1,122 @@ +# SPIKE Protocol + +## Overview + +Time-boxed technical feasibility exploration. Answer "Can we do X?" and "What would it take?" before committing to a full SPIR project. + +**Core Principle**: Stay focused on the question. Once you can answer it, write findings and stop. + +## When to Use + +**Use for**: Quick technical feasibility investigations, proof-of-concept explorations, "can we do X?" questions, evaluating approaches before committing to SPIR + +**Skip for**: Production code (use SPIR), formal hypothesis testing (use EXPERIMENT), bug fixes (use BUGFIX), well-understood implementations (use TICK) + +### Spike vs Experiment + +| | Spike | Experiment | +|---|---|---| +| **Goal** | Answer a feasibility question | Test a formal hypothesis | +| **Structure** | Lightweight guidance | Formal phases (hypothesis/design/execute/analyze) | +| **Output** | Findings document | Experiment notes with metrics | +| **Rigor** | Exploration-first | Measurement-first | +| **Time** | Short (hours) | Longer (days) | + +## Spawning a Spike + +```bash +af spawn --task "Can we use WebSockets for real-time updates?" --protocol spike +af spawn --task "What would it take to support SQLite FTS?" --protocol spike +``` + +Spikes are always soft mode — no porch orchestration, no gates, no consultation. + +## Recommended Workflow + +The following 3-step workflow is **guidance only** — not enforced by porch. Follow it, skip steps, or reorder as the investigation demands. + +### Step 1: Research + +- Read documentation, examine existing code, search for prior art +- Identify constraints, dependencies, and potential blockers +- Understand the problem space before writing any code +- Check if someone has already investigated this (look in `codev/spikes/`) + +### Step 2: Iterate + +- Build minimal proof-of-concept code +- Try different approaches, hit walls, pivot +- Focus on answering the feasibility question, not building production code +- **Skip this step** if the answer is clear from research alone + +### Step 3: Findings + +- Write the findings document at `codev/spikes/-.md` +- Use the template: `codev/protocols/spike/templates/findings.md` +- Provide a clear feasibility verdict +- Commit and notify the architect + +## Output + +Findings are stored in `codev/spikes/` using the pattern: `-.md` + +Examples: +- `codev/spikes/462-websocket-feasibility.md` +- `codev/spikes/475-sqlite-fts-performance.md` + +The `` is the GitHub issue number or project ID. + +## Proof-of-Concept Code + +POC code from the iterate step is committed to the spike branch alongside the findings document. It serves as evidence supporting the findings. However: + +- POC code does NOT need tests, polish, or production quality +- POC code does NOT get merged to main — it stays on the spike branch +- The findings document is the primary deliverable; the code is supporting evidence +- If the spike leads to a SPIR project, the builder starts fresh + +## Outcome Handling + +- **Feasible**: Write findings with recommended approach and effort estimate. Architect decides whether to create a SPIR project. +- **Not Feasible**: Write findings documenting why, what was tried, and what alternatives exist. This prevents future teams from repeating the investigation. +- **Feasible with Caveats**: Write findings with conditions, risks, and trade-offs. + +In all cases, notify the architect: +```bash +af send architect "Spike complete. Verdict: [feasible/not feasible/caveats]" +``` + +## Git Workflow + +### Commits +``` +[Spike 462] Research: WebSocket library comparison +[Spike 462] Iterate: POC with ws library +[Spike 462] Findings: WebSockets feasible for real-time updates +``` + +### When to Commit +- After significant research findings +- After each iteration attempt +- When writing the findings document (final commit) + +## Integration with Other Protocols + +### Spike -> SPIR +When a spike validates feasibility: +1. Create a SPIR spec referencing the spike findings +2. Use findings to inform the solution approach +3. Reference effort estimate for planning + +Example spec reference: +```markdown +## Background +Spike 462 confirmed WebSocket feasibility with the `ws` library. +See: codev/spikes/462-websocket-feasibility.md +``` + +### Spike -> "Do Not Pursue" +When a spike finds something is not feasible: +1. Document clearly in findings +2. Close the related GitHub issue with a link to findings +3. The findings become institutional knowledge diff --git a/codev/protocols/spike/templates/findings.md b/codev/protocols/spike/templates/findings.md new file mode 100644 index 0000000..3fa8c2c --- /dev/null +++ b/codev/protocols/spike/templates/findings.md @@ -0,0 +1,67 @@ +# Spike: [Title] + +**Date**: YYYY-MM-DD + +**Verdict**: Feasible | Not Feasible | Feasible with Caveats + +## Question + +What technical question was being investigated? Be specific: +- What are you trying to determine? +- What prompted this investigation? +- What decision depends on the answer? + +## Research Summary + +What was explored during the research phase: +- Documentation read +- Existing code examined +- Prior art found +- Key constraints identified + +## Approaches Tried + +What was built or tested during the iterate phase: + +### Approach 1: [Name] +- **What**: Brief description of what was tried +- **Result**: What happened +- **Verdict**: Worked / Didn't work / Partially worked + +### Approach 2: [Name] +*(Add more approaches as needed, or remove if research alone answered the question)* + +## Constraints Discovered + +Technical limitations, dependencies, and gotchas found during the investigation: +- [Constraint 1] +- [Constraint 2] + +## Recommended Approach + +*(If feasible)* How should full implementation proceed? +- Recommended library/technique/pattern +- Key architectural decisions +- Things to watch out for + +*(If not feasible)* Why not, and what alternatives exist? + +## Effort Estimate + +Rough sizing for a full SPIR project: **Small** | **Medium** | **Large** + +- Small: < 300 LOC, 1-2 files, straightforward +- Medium: 300-1000 LOC, multiple files, some complexity +- Large: 1000+ LOC, architectural changes, significant complexity + +## Next Steps + +- [ ] [Recommended action — e.g., "Create SPIR spec for WebSocket integration"] +- [ ] [Or: "Do not pursue — blocked by X"] +- [ ] [Or: "Investigate Y further before deciding"] + +## References + +- [Link to relevant documentation] +- [Link to relevant code/commits] +- [Link to external resources consulted] diff --git a/codev/protocols/spir/builder-prompt.md b/codev/protocols/spir/builder-prompt.md new file mode 100644 index 0000000..1f932b6 --- /dev/null +++ b/codev/protocols/spir/builder-prompt.md @@ -0,0 +1,75 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the protocol document yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Run consultations manually when the protocol calls for them +- You have flexibility in execution, but must stay compliant with the protocol +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals +- Do not deviate from the porch-driven workflow + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +- **NEVER skip the 3-way review** — always follow porch next → porch done cycle +- **NEVER advance plan phases manually** — porch handles phase transitions after unanimous review approval +{{/if}} + +## Protocol +Follow the SPIR protocol: `codev/protocols/spir/protocol.md` +Read and internalize the protocol before starting any work. + +{{#if spec}} +## Spec +Read the specification at: `{{spec.path}}` +{{/if}} + +{{#if plan}} +## Plan +Follow the implementation plan at: `{{plan.path}}` +{{/if}} + +{{#if issue}} +## Issue #{{issue.number}} +**Title**: {{issue.title}} + +**Description**: +{{issue.body}} +{{/if}} + +{{#if task}} +## Task +{{task_text}} +{{/if}} + +## Notifications +Always use `af send architect "..."` to notify the architect at key moments: +- **Gate reached**: `af send architect "Project {{project_id}}: ready for approval"` +- **PR ready**: `af send architect "PR #N ready for review (project {{project_id}})"` +- **PR merged**: `af send architect "Project {{project_id}} complete. PR merged. Ready for cleanup."` +- **Blocked**: `af send architect "Blocked on project {{project_id}}: [reason]"` + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the protocol document thoroughly +2. Review the spec and plan (if available) +3. Begin implementation following the protocol phases diff --git a/codev/protocols/spir/consult-types/impl-review.md b/codev/protocols/spir/consult-types/impl-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/spir/consult-types/impl-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/spir/consult-types/phase-review.md b/codev/protocols/spir/consult-types/phase-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/spir/consult-types/phase-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/spir/consult-types/plan-review.md b/codev/protocols/spir/consult-types/plan-review.md new file mode 100644 index 0000000..585085d --- /dev/null +++ b/codev/protocols/spir/consult-types/plan-review.md @@ -0,0 +1,59 @@ +# Plan Review Prompt + +## Context +You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +## Focus Areas + +1. **Spec Coverage** + - Does the plan address all requirements in the spec? + - Are there spec requirements not covered by any phase? + - Are there phases that go beyond the spec scope? + +2. **Phase Breakdown** + - Are phases appropriately sized (not too large or too small)? + - Is the sequence logical (dependencies respected)? + - Can each phase be completed and committed independently? + +3. **Technical Approach** + - Is the implementation approach sound? + - Are the right files/modules being modified? + - Are there obvious better approaches being missed? + +4. **Testability** + - Does each phase have clear test criteria? + - Will the Defend step (writing tests) be feasible? + - Are edge cases from the spec addressable? + +5. **Risk Assessment** + - Are there potential blockers not addressed? + - Are dependencies on other systems identified? + - Is the plan realistic given constraints? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Plan is ready for human review +- `REQUEST_CHANGES`: Significant issues with approach or coverage +- `COMMENT`: Minor suggestions, plan is workable but could improve + +## Notes + +- The spec has already been approved - don't re-litigate spec decisions +- Focus on the quality of the plan as a guide for builders +- Consider: Would a builder be able to follow this plan successfully? +- If referencing existing code, verify file paths seem accurate diff --git a/codev/protocols/spir/consult-types/pr-review.md b/codev/protocols/spir/consult-types/pr-review.md new file mode 100644 index 0000000..048c23f --- /dev/null +++ b/codev/protocols/spir/consult-types/pr-review.md @@ -0,0 +1,72 @@ +# PR Ready Review Prompt + +## Context +You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. + +## Focus Areas + +1. **Completeness** + - Are all spec requirements implemented? + - Are all plan phases complete? + - Is the review document written (`codev/reviews/XXXX-name.md`)? + - Are all commits properly formatted (`[Spec XXXX][Phase]`)? + +2. **Test Status** + - Do all tests pass? + - Is test coverage adequate for the changes? + - Are there any skipped or flaky tests? + +3. **Code Cleanliness** + - Is there any debug code left in? + - Are there any TODO comments that should be resolved? + - Are there any `// REVIEW:` comments that weren't addressed? + - Is the code properly formatted? + +4. **Documentation** + - Are inline comments clear where needed? + - Is the review document comprehensive? + - Are any new APIs documented? + +5. **PR Readiness** + - Is the branch up to date with main? + - Are commits atomic and well-described? + - Is the change diff reasonable in size? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... + +PR_SUMMARY: | + ## Summary + [2-3 sentences describing what this PR does] + + ## Key Changes + - [Change 1] + - [Change 2] + + ## Test Plan + - [How to test] +``` + +**Verdict meanings:** +- `APPROVE`: Ready to create PR +- `REQUEST_CHANGES`: Issues to fix before PR creation +- `COMMENT`: Minor items, can create PR but note feedback + +## Notes + +- This is the builder's final self-review before hand-off +- The PR_SUMMARY in your output can be used as the PR description +- Focus on "is this ready for someone else to review" not "is this perfect" +- Any issues found here are cheaper to fix than during integration review diff --git a/codev/protocols/spir/consult-types/spec-review.md b/codev/protocols/spir/consult-types/spec-review.md new file mode 100644 index 0000000..7c9c157 --- /dev/null +++ b/codev/protocols/spir/consult-types/spec-review.md @@ -0,0 +1,55 @@ +# Specification Review Prompt + +## Context +You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +## Focus Areas + +1. **Completeness** + - Are all requirements clearly stated? + - Are success criteria defined? + - Are edge cases considered? + - Is scope well-bounded (not too broad or vague)? + +2. **Correctness** + - Do requirements make sense technically? + - Are there contradictions? + - Is the problem statement accurate? + +3. **Feasibility** + - Can this be implemented with available tools/constraints? + - Are there obvious technical blockers? + - Is the scope realistic for a single spec? + +4. **Clarity** + - Would a builder understand what to build? + - Are acceptance criteria testable? + - Is terminology consistent? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Spec is ready for human review +- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but consider feedback + +## Notes + +- You are NOT reviewing code - you are reviewing the specification document +- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) +- Be constructive - identify issues AND suggest solutions +- If the spec references other specs, note if context seems missing diff --git a/codev/protocols/spir/prompts/implement.md b/codev/protocols/spir/prompts/implement.md new file mode 100644 index 0000000..bacc850 --- /dev/null +++ b/codev/protocols/spir/prompts/implement.md @@ -0,0 +1,215 @@ +# IMPLEMENT Phase Prompt + +You are executing the **IMPLEMENT** phase of the SPIR protocol. + +## Your Goal + +Write clean, well-structured code AND tests that implement the current plan phase. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Plan Phase**: {{plan_phase_id}} - {{plan_phase_title}} + +## ⚠️ SCOPE RESTRICTION — READ THIS FIRST + +**You are implementing ONLY the current plan phase: {{plan_phase_id}} ({{plan_phase_title}}).** + +- **DO NOT** implement other phases. Other phases will be handled in subsequent porch iterations. +- **DO NOT** read the full plan file and implement everything you see. +- The plan phase details are included below under "Current Plan Phase Details". That is your ONLY scope. +- If you need to reference the spec for requirements, read `codev/specs/{{project_id}}-*.md` but ONLY implement what the current phase requires. + +## What Happens After You Finish + +When you signal `PHASE_COMPLETE`, porch will: +1. Run 3-way consultation (Gemini, Codex, Claude) on your implementation +2. Check that tests exist and pass +3. If reviewers request changes, you'll be respawned with their feedback +4. Once approved, porch commits and moves to the next plan phase + +## Spec Compliance (CRITICAL) + +**The spec is the source of truth. Code that doesn't match the spec is wrong, even if it "works".** + +### Trust Hierarchy + +``` +SPEC (source of truth) + ↓ +PLAN (implementation guide derived from spec) + ↓ +EXISTING CODE (NOT TRUSTED - must be validated against spec) +``` + +**Never trust existing code over the spec.** Previous implementations may have drifted. + +### Pre-Implementation Sanity Check (PISC) + +**Before writing ANY code:** + +1. ✅ "Have I read the spec in the last 30 minutes?" +2. ✅ "If the spec has a 'Traps to Avoid' section, have I read it?" +3. ✅ "Does my approach match the spec's Technical Implementation section?" +4. ✅ "If the spec has code examples, am I following them?" +5. ✅ "Does the existing code I'm building on actually match the spec?" + +**If ANY answer is "no" or "unsure" → STOP and re-read the spec.** + +### Avoiding "Fixing Mode" + +A dangerous pattern: You start looking at symptoms in code, making incremental fixes, copying existing patterns - without going back to the spec. This leads to: +- Cargo-culting patterns that may be wrong +- Building on broken foundations +- Implementing something different from the spec + +**When you catch yourself "fixing" code:** +1. STOP +2. Ask: "What does the spec say about this?" +3. Re-read the spec's Traps to Avoid section +4. Verify existing code matches the spec before building on it + +## Prerequisites + +Before implementing, verify: +1. Previous phase (if any) is committed to git +2. You've read the plan phase you're implementing +3. You understand the success criteria for this phase +4. Dependencies from earlier phases are available + +## Process + +### 1. Review the Plan Phase + +Read the current phase in the plan: +- What is the objective? +- What files need to be created/modified? +- What are the success criteria? +- What dependencies exist? + +### 2. Set Up + +- Verify you're on the correct branch +- Check that previous phase is committed: `git log --oneline -5` +- Ensure build passes before starting: `npm run build` (or equivalent) + +### 3. Implement the Code + +Write the code following these principles: + +**Code Quality Standards**: +- Self-documenting code (clear names, obvious structure) +- No commented-out code +- No debug prints in final code +- Explicit error handling +- Follow project style guide + +**Implementation Approach**: +- Work on one file at a time +- Make small, incremental changes +- Document complex logic with comments + +### 4. Write Tests + +**Tests are required.** For each piece of functionality you implement: + +- Write unit tests for core logic +- Write integration tests if the phase involves multiple components +- Test error cases and edge conditions +- Ensure tests are deterministic (no flaky tests) + +**Test file locations** (follow project conventions): +- `tests/` or `__tests__/` directories +- `*.test.ts` or `*.spec.ts` naming + +### 5. Verify Everything Works + +Run both build and tests: + +```bash +npm run build # Must pass +npm test # Must pass +``` + +**Important**: Don't assume these commands exist. Check `package.json` first. + +Fix any errors before signaling completion. + +### 6. Self-Review + +Before signaling completion: +- Read through all code changes +- Read through all test changes +- Verify code matches the spec requirements +- Ensure no accidental debug code +- Check test coverage is adequate + +## Output + +When complete, you should have: +- Modified/created source files as specified in the plan phase +- Tests covering the new functionality +- All build checks passing +- All tests passing + +## Signals + +When implementation AND tests are complete and passing: + +``` +PHASE_COMPLETE +``` + +If you encounter a blocker: + +``` +BLOCKED:reason goes here +``` + +If you need spec/plan clarification: + +``` + +Your specific questions here + +``` + +## Important Notes + +1. **Follow the plan** - Implement what's specified, not more +2. **Don't over-engineer** - Simplest solution that works +3. **Don't skip error handling** - But don't go overboard either +4. **Keep changes focused** - Only touch files in this phase +5. **Build AND tests must pass** - Don't signal complete until both pass +6. **Write tests** - Every implementation phase needs tests + +## What NOT to Do + +- Don't modify files outside this phase's scope +- Don't add features not in the spec +- Don't leave TODO comments for later (fix now or note as blocker) +- Don't skip writing tests +- Don't use `git add .` or `git add -A` when you commit (security risk) + +## Handling Problems + +**If the plan is unclear**: +Signal `AWAITING_INPUT` with your specific question. + +**If you discover the spec is wrong**: +Signal `BLOCKED` and explain the issue. The Architect may need to update the spec. + +**If a dependency is missing**: +Signal `BLOCKED` with details about what's missing. + +**If build or tests fail and you can't fix it**: +Signal `BLOCKED` with the error message. + +**If you encounter pre-existing flaky tests** (tests that fail intermittently but are unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use workarounds to avoid the failure +3. **DO** mark the flaky test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: intermittent timeout, skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section so the team can follow up +5. Commit the skip and continue with your work diff --git a/codev/protocols/spir/prompts/plan.md b/codev/protocols/spir/prompts/plan.md new file mode 100644 index 0000000..3549654 --- /dev/null +++ b/codev/protocols/spir/prompts/plan.md @@ -0,0 +1,150 @@ +# PLAN Phase Prompt + +You are executing the **PLAN** phase of the SPIR protocol. + +## Your Goal + +Transform the approved specification into an executable implementation plan with clear phases. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` +- **Plan File**: `codev/plans/{{artifact_name}}.md` + +## Prerequisites + +Before planning, verify: +1. The specification exists and has been approved +2. You've read and understood the entire spec +3. Success criteria are clear and measurable + +## Process + +### 1. Analyze the Specification + +Read the spec thoroughly. Identify: +- All functional requirements +- Non-functional requirements +- Dependencies and constraints +- Success criteria to validate against + +### 2. Identify Implementation Phases + +Break the work into logical phases. Each phase should be: +- **Self-contained** - A complete unit of functionality +- **Independently testable** - Can be verified on its own +- **Valuable** - Delivers observable progress +- **Committable** - Can be a single atomic commit + +Good phase examples: +- "Database Schema" - Creates all tables/migrations +- "Core API Endpoints" - Implements main REST routes +- "Authentication Flow" - Handles login/logout/session + +Bad phase examples: +- "Setup" - Too vague +- "Part 1" - Not descriptive +- "Everything" - Not broken down + +### 3. Define Each Phase + +For each phase, document: +- **Objective** - Single clear goal +- **Files to modify/create** - Specific paths +- **Dependencies** - Which phases must complete first +- **Success criteria** - How to know it's done +- **Test approach** - What tests will verify it + +### 4. Order Phases by Dependencies + +Arrange phases so dependencies are satisfied: +``` +Phase 1: Database Schema (no dependencies) +Phase 2: Data Models (depends on Phase 1) +Phase 3: API Endpoints (depends on Phase 2) +Phase 4: Frontend Integration (depends on Phase 3) +``` + +### 5. Finalize + +After completing the plan draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + +## Output + +Create the plan file at `codev/plans/{{artifact_name}}.md`. + +Use the plan template from `codev/protocols/spir/templates/plan.md` if available. + +### Plan Structure + +```markdown +# Implementation Plan: {{title}} + +## Overview +Brief summary of what will be implemented. + +## Phases + +### Phase 1: [Name] +- **Objective**: [Single clear goal] +- **Files**: [List of files to create/modify] +- **Dependencies**: None +- **Success Criteria**: [How to verify completion] +- **Tests**: [What tests will be written] + +### Phase 2: [Name] +- **Objective**: [Single clear goal] +- **Files**: [List of files] +- **Dependencies**: Phase 1 +- **Success Criteria**: [Verification method] +- **Tests**: [Test approach] + +[Continue for all phases...] + +## Risk Assessment +- [Risk 1]: [Mitigation] +- [Risk 2]: [Mitigation] + +``` + +## Signals + +Emit appropriate signals based on your progress: + +- After completing the plan draft: + ``` + PLAN_DRAFTED + ``` + +## Commit Cadence + +Make commits at these milestones: +1. `[Spec {{project_id}}] Initial implementation plan` +2. `[Spec {{project_id}}] Plan with multi-agent review` +3. `[Spec {{project_id}}] Plan with user feedback` +4. `[Spec {{project_id}}] Final approved plan` + +**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: +```bash +git add codev/plans/{{artifact_name}}.md +``` + +## Important Notes + +1. **No time estimates** - Don't include hours/days/weeks +3. **Be specific about files** - Exact paths, not "the config file" +4. **Keep phases small** - 1-3 files per phase is ideal +5. **Document dependencies clearly** - Prevents blocked work + +## What NOT to Do + +- Don't run `consult` commands yourself (porch handles consultations) +- Don't write code (that's for Implement phase) +- Don't estimate time (meaningless in AI development) +- Don't create phases that can't be independently tested +- Don't skip dependency analysis +- Don't make phases too large (if >5 files, split it) +- Don't use `git add .` or `git add -A` (security risk) diff --git a/codev/protocols/spir/prompts/review.md b/codev/protocols/spir/prompts/review.md new file mode 100644 index 0000000..dbffd4b --- /dev/null +++ b/codev/protocols/spir/prompts/review.md @@ -0,0 +1,259 @@ +# REVIEW Phase Prompt + +You are executing the **REVIEW** phase of the SPIR protocol. + +## Your Goal + +Perform a comprehensive review, document lessons learned, and prepare for PR submission. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` +- **Plan File**: `codev/plans/{{artifact_name}}.md` +- **Review File**: `codev/reviews/{{artifact_name}}.md` + +## Prerequisites + +Before review, verify: +1. All implementation phases are committed +2. All tests are passing +3. Build is passing +4. Spec compliance verified for all phases + +Verify commits: `git log --oneline | grep "[Spec {{project_id}}]"` + +## Process + +### 1. Comprehensive Review + +Review the entire implementation: + +**Code Quality**: +- Is the code readable and maintainable? +- Are there any code smells? +- Is error handling consistent? +- Are there any security concerns? + +**Architecture**: +- Does the implementation fit well with existing code? +- Are there any architectural concerns? +- Is the design scalable if needed? + +**Documentation**: +- Is code adequately commented where needed? +- Are public APIs documented? +- Is README updated if needed? + +### 2. Spec Comparison + +Compare final implementation to original specification: + +- What was delivered vs what was specified? +- Any deviations? Document why. +- All success criteria met? + +### 3. Create Review Document + +Create `codev/reviews/{{artifact_name}}.md`: + +```markdown +# Review: {{title}} + +## Summary +Brief description of what was implemented. + +## Spec Compliance +- [x] Requirement 1: Implemented as specified +- [x] Requirement 2: Implemented with deviation (see below) +- [x] Requirement 3: Implemented as specified + +## Deviations from Plan +- **Phase X**: [What changed and why] + +## Lessons Learned + +### What Went Well +- [Positive observation 1] +- [Positive observation 2] + +### Challenges Encountered +- [Challenge 1]: [How it was resolved] +- [Challenge 2]: [How it was resolved] + +### What Would Be Done Differently +- [Insight 1] +- [Insight 2] + +### Methodology Improvements +- [Suggested improvement to SPIR protocol] +- [Suggested improvement to tooling] + +## Technical Debt +- [Any shortcuts taken that should be addressed later] + +## Consultation Feedback + +[See instructions below] + +## Flaky Tests +- [Any pre-existing tests that were skipped as flaky during this project] +- [Include test name, file path, and observed failure mode] +- [If none: "No flaky tests encountered"] + +## Follow-up Items +- [Any items identified for future work] +``` + +### 3b. Include Consultation Feedback + +**IMPORTANT**: The review document MUST include a `## Consultation Feedback` section that summarizes all consultation concerns raised during every phase of the project and how the builder responded. + +Read the consultation output files from the project directory (`codev/projects/{project-id}-*/`). For each phase that had consultation, create a subsection organized by phase, round, and model: + +```markdown +## Consultation Feedback + +### Specify Phase (Round 1) + +#### Gemini +- **Concern**: [Summary of the concern] + - **Addressed**: [What was changed to resolve it] + +#### Codex +- **Concern**: [Summary] + - **Rebutted**: [Why the current approach is correct] + +#### Claude +- No concerns raised (APPROVE) + +### Plan Phase (Round 1) +... +``` + +**Response types** — each concern gets exactly one: +- **Addressed**: Builder made a change to resolve the concern +- **Rebutted**: Builder explains why the concern doesn't apply +- **N/A**: Concern is out of scope, already handled elsewhere, or moot + +**Edge cases**: +- If all reviewers approved with no concerns: "No concerns raised — all consultations approved" +- For COMMENT verdicts: include their feedback (non-blocking but useful context) +- For CONSULT_ERROR (model failure): note "Consultation failed for [model]" +- If a phase had multiple rounds, give each round its own subsection + +### 4. Update Architecture and Lessons Learned Documentation + +**MANDATORY**: The review document MUST include `## Architecture Updates` and `## Lessons Learned Updates` sections. Porch will block advancement if these are missing. + +**Architecture Updates** (`codev/resources/arch.md`): +1. Read the current `codev/resources/arch.md` +2. Determine if this project introduced architectural changes worth documenting (new subsystems, data flows, design decisions, invariants, file locations) +3. If yes: make the updates to arch.md and describe what you changed in the `## Architecture Updates` section of the review +4. If no: write "No architecture updates needed" in the section with a brief explanation (e.g., "This was a template-only change with no new subsystems or data flows") + +**Lessons Learned Updates** (`codev/resources/lessons-learned.md`): +1. Read the current `codev/resources/lessons-learned.md` +2. Determine if this project produced generalizable lessons (patterns, anti-patterns, debugging insights, process improvements) +3. If yes: add entries to lessons-learned.md and describe what you added in the `## Lessons Learned Updates` section of the review +4. If no: write "No lessons learned updates needed" in the section with a brief explanation (e.g., "Straightforward implementation with no novel insights beyond existing entries") + +### 4b. Update Other Documentation + +If needed, also update: +- README.md (new features, changed behavior) +- API documentation + +### 5. Final Verification + +Before PR: +- [ ] All tests pass (use project-specific test command) +- [ ] Build passes (use project-specific build command) +- [ ] Lint passes (if configured) +- [ ] No uncommitted changes: `git status` +- [ ] Review document complete + +### 6. Create Pull Request + +**IMPORTANT: Create the PR BEFORE signaling completion.** The PR must exist so that +porch consultation reviews the actual PR, and the architect can review a real PR +when the pr gate fires. + +```bash +gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF' +## Summary +[Brief description of the implementation] + +## Changes +- [Change 1] +- [Change 2] + +## Testing +- All unit tests passing +- Integration tests added for [X] +- Manual testing completed for [Y] + +## Spec +Link: codev/specs/{{artifact_name}}.md + +## Review +Link: codev/reviews/{{artifact_name}}.md +EOF +)" +``` + +### 7. Signal Completion + +After the PR is created, signal completion. Porch will run 3-way consultation +(Gemini, Codex, Claude) automatically via the verify step. If reviewers request +changes, you'll be respawned with their feedback. + +## Output + +- Review document at `codev/reviews/{{artifact_name}}.md` +- Updated documentation (if needed) +- Pull request created and ready for review + +## Signals + +- After review document is complete: + ``` + REVIEW_COMPLETE + ``` + +- After PR is created — signal completion so porch runs consultation: + ``` + PR_READY + ``` + +## Important Notes + +1. **Be honest in lessons learned** - Future you will thank present you +3. **Document deviations** - They're not failures, they're learnings +4. **Update methodology** - If you found a better way, document it +5. **Don't skip the checklist** - It catches last-minute issues +6. **Clean PR description** - Makes review easier + +## What NOT to Do + +- Don't run `consult` commands yourself (porch handles consultations) +- Don't skip lessons learned ("nothing to report") +- Don't merge your own PR (Architect handles integration) +- Don't leave uncommitted changes +- Don't forget to update documentation +- Don't rush this phase - it's valuable for learning +- Don't use `git add .` or `git add -A` (security risk) + +## Review Prompts for Reflection + +Ask yourself: +- What surprised me during implementation? +- Where did I spend the most time? Was it avoidable? +- What would have helped me go faster? +- Did the spec adequately describe what was needed? +- Did the plan phases make sense in hindsight? +- What tests caught issues? What tests were unnecessary? + +Capture these reflections in the lessons learned section. diff --git a/codev/protocols/spir/prompts/specify.md b/codev/protocols/spir/prompts/specify.md new file mode 100644 index 0000000..6da1868 --- /dev/null +++ b/codev/protocols/spir/prompts/specify.md @@ -0,0 +1,139 @@ +# SPECIFY Phase Prompt + +You are executing the **SPECIFY** phase of the SPIR protocol. + +## Your Goal + +Create a comprehensive specification document that thoroughly explores the problem space and proposed solution. + +## Context + +- **Project ID**: {{project_id}} +- **Project Title**: {{title}} +- **Current State**: {{current_state}} +- **Spec File**: `codev/specs/{{artifact_name}}.md` + +## Process + +### 0. Check for Existing Spec (ALWAYS DO THIS FIRST) + +**Before asking ANY questions**, check if a spec already exists: + +```bash +ls codev/specs/{{project_id}}-*.md +``` + +**If a spec file exists:** +1. READ IT COMPLETELY - the answers to your questions are already there +2. The spec author has already made the key decisions +3. DO NOT ask clarifying questions - proceed directly to consultation +4. Your job is to REVIEW and IMPROVE the existing spec, not rewrite it from scratch + +**If no spec exists:** Proceed to Step 1 below. + +### 1. Clarifying Questions (ONLY IF NO SPEC EXISTS) + +Before writing anything, ask clarifying questions to understand: +- What problem is being solved? +- Who are the stakeholders? +- What are the constraints? +- What's in scope vs out of scope? +- What does success look like? + +If this is your first iteration AND no spec exists, ask these questions now and wait for answers. + +**CRITICAL**: Do NOT ask questions if a spec already exists. The spec IS the answer. + +**On subsequent iterations**: If questions were already answered, acknowledge the answers and proceed to the next step. + +### 2. Problem Analysis + +Once you have answers, document: +- The problem being solved (clearly articulated) +- Current state vs desired state +- Stakeholders and their needs +- Assumptions and constraints + +### 3. Solution Exploration + +Generate multiple solution approaches. For each: +- Technical design overview +- Trade-offs (pros/cons) +- Complexity assessment +- Risk assessment + +### 4. Open Questions + +List uncertainties categorized as: +- **Critical** - blocks progress +- **Important** - affects design +- **Nice-to-know** - optimization + +### 5. Success Criteria + +Define measurable acceptance criteria: +- Functional requirements (MUST, SHOULD, COULD) +- Non-functional requirements (performance, security) +- Test scenarios + +### 6. Finalize + +After completing the spec draft, signal completion. Porch will run 3-way consultation (Gemini, Codex, Claude) automatically via the verify step. If reviewers request changes, you'll be respawned with their feedback. + +## Output + +Create or update the specification file at `codev/specs/{{artifact_name}}.md`. + +**IMPORTANT**: Keep spec/plan/review filenames in sync: +- Spec: `codev/specs/{{artifact_name}}.md` +- Plan: `codev/plans/{{artifact_name}}.md` +- Review: `codev/reviews/{{artifact_name}}.md` + +## Signals + +Emit appropriate signals based on your progress: + +- When waiting for clarifying question answers, **include your questions in the signal**: + ``` + + Please answer these questions: + 1. What should the primary use case be - internal tooling or customer-facing? + 2. What are the key constraints we should consider? + 3. Who are the main stakeholders? + + ``` + + The content inside the signal tag is displayed prominently to the user. + +- After completing the initial spec draft: + ``` + SPEC_DRAFTED + ``` + + +## Commit Cadence + +Make commits at these milestones: +1. `[Spec {{project_id}}] Initial specification draft` +2. `[Spec {{project_id}}] Specification with multi-agent review` +3. `[Spec {{project_id}}] Specification with user feedback` +4. `[Spec {{project_id}}] Final approved specification` + +**CRITICAL**: Never use `git add .` or `git add -A`. Always stage specific files: +```bash +git add codev/specs/{{artifact_name}}.md +``` + +## Important Notes + +1. **Be thorough** - A good spec prevents implementation problems +3. **Be specific** - Vague specs lead to wrong implementations +4. **Include examples** - Concrete examples clarify intent + +## What NOT to Do + +- Don't run `consult` commands yourself (porch handles consultations) +- Don't include implementation details (that's for the Plan phase) +- Don't estimate time (AI makes time estimates meaningless) +- Don't start coding (you're in Specify, not Implement) +- Don't use `git add .` or `git add -A` (security risk) diff --git a/codev/protocols/spir/protocol.json b/codev/protocols/spir/protocol.json new file mode 100644 index 0000000..ca5820f --- /dev/null +++ b/codev/protocols/spir/protocol.json @@ -0,0 +1,164 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "spir", + "alias": "spider", + "version": "2.2.0", + "description": "SPIR: Specify → Plan → Implement → Review with build-verify cycles", + "input": { + "type": "spec", + "required": false, + "default_for": ["--project", "-p"] + }, + "phases": [ + { + "id": "specify", + "name": "Specify", + "description": "Write specification with 3-way review", + "type": "build_verify", + "build": { + "prompt": "specify.md", + "artifact": "codev/specs/${PROJECT_TITLE}.md" + }, + "verify": { + "type": "spec", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "gate": "spec-approval", + "next": "plan" + }, + { + "id": "plan", + "name": "Plan", + "description": "Write implementation plan with 3-way review", + "type": "build_verify", + "build": { + "prompt": "plan.md", + "artifact": "codev/plans/${PROJECT_TITLE}.md" + }, + "verify": { + "type": "plan", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "plan_exists": "test -f codev/plans/${PROJECT_TITLE}.md", + "has_phases_json": "grep -q '\"phases\":' codev/plans/${PROJECT_TITLE}.md", + "min_two_phases": "grep -o '\"id\": *\"[^\"]*\"' codev/plans/${PROJECT_TITLE}.md | wc -l | awk '$1 >= 2 {exit 0} {exit 1}'" + }, + "gate": "plan-approval", + "next": "implement" + }, + { + "id": "implement", + "name": "Implement", + "description": "Implement code with 3-way review per plan phase", + "type": "per_plan_phase", + "build": { + "prompt": "implement.md", + "artifact": "src/**/*.{ts,tsx,js,jsx}" + }, + "verify": { + "type": "impl", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + }, + "tests": { + "command": "npm test -- --exclude='**/e2e/**'", + "description": "Unit tests only - e2e tests run in review phase", + "on_fail": "retry", + "max_retries": 2 + } + }, + "transition": { + "on_complete": "implement", + "on_all_phases_complete": "review" + } + }, + { + "id": "review", + "name": "Review", + "description": "Final review and PR with 3-way review", + "type": "build_verify", + "build": { + "prompt": "review.md", + "artifact": "codev/reviews/${PROJECT_TITLE}.md" + }, + "verify": { + "type": "pr", + "models": ["gemini", "codex", "claude"], + "parallel": true + }, + "max_iterations": 1, + "on_complete": { + "commit": true, + "push": true + }, + "checks": { + "pr_exists": { + "command": "gh pr list --state all --head \"$(git branch --show-current)\" --json number --jq 'length' | grep -q '^[1-9]'", + "description": "PR must be created before signaling completion" + }, + "review_has_arch_updates": { + "command": "grep -q '## Architecture Updates' codev/reviews/${PROJECT_TITLE}.md", + "description": "Review must include '## Architecture Updates' section (what changed in arch.md, or why no changes needed)" + }, + "review_has_lessons_updates": { + "command": "grep -q '## Lessons Learned Updates' codev/reviews/${PROJECT_TITLE}.md", + "description": "Review must include '## Lessons Learned Updates' section (what changed in lessons-learned.md, or why no changes needed)" + }, + "e2e_tests": { + "command": "npm run test:e2e 2>&1 || echo 'e2e tests skipped (not configured)'", + "description": "Full e2e test suite - only runs in review phase", + "optional": true + } + }, + "gate": "pr", + "next": null + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current build phase is complete", + "transitions_to": "verify" + }, + "BLOCKED": { + "description": "Signal implementation is blocked", + "requires": "reason" + } + }, + "phase_completion": { + "build_succeeds": "npm run build 2>&1", + "tests_pass": "npm test 2>&1", + "commit_has_code": "git log -1 --name-only --pretty=format: | grep -qE '\\.(ts|tsx|js|jsx|py|go|rs)$'" + }, + "defaults": { + "mode": "strict", + "max_iterations": 1, + "verify": { + "models": ["gemini", "codex", "claude"], + "parallel": true + } + } +} diff --git a/codev/protocols/spir/protocol.md b/codev/protocols/spir/protocol.md new file mode 100644 index 0000000..a08b97e --- /dev/null +++ b/codev/protocols/spir/protocol.md @@ -0,0 +1,653 @@ +# SPIR Protocol + +> **SPIR** = **S**pecify → **P**lan → **I**mplement → **R**eview +> +> Each phase has one build-verify cycle with 3-way consultation. + +> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands. + +## Prerequisites + +**Clean Worktree Before Spawning Builders**: +- All specs, plans, and local changes **MUST be committed** before `af spawn` +- Builders work in git worktrees branched from HEAD — uncommitted files are invisible +- This includes `codev update` results, spec drafts, and plan approvals +- The `af spawn` command enforces this (use `--force` to override) + +**Required for Multi-Agent Consultation**: +- The `consult` CLI must be available (installed with `npm install -g @cluesmith/codev`) +- At least one consultation backend: `claude`, `gemini-cli`, or `codex` +- Check with: `codev doctor` or `consult --help` + +## Protocol Configuration + +### Multi-Agent Consultation (ENABLED BY DEFAULT) + +**DEFAULT BEHAVIOR:** +Multi-agent consultation is **ENABLED BY DEFAULT** when using SPIR protocol. + +**DEFAULT AGENTS:** +- **GPT-5 Codex**: Primary reviewer for architecture, feasibility, and code quality +- **Gemini Pro**: Secondary reviewer for completeness, edge cases, and alternative approaches + +**DISABLING CONSULTATION:** +To run SPIR without consultation, say "without consultation" when starting work. + +**CUSTOM AGENTS:** +The user can specify different agents by saying: "use SPIR with consultation from [agent1] and [agent2]" + +**CONSULTATION BEHAVIOR:** +- DEFAULT: MANDATORY consultation with GPT-5 and Gemini Pro at EVERY checkpoint +- When explicitly disabled: Skip all consultation steps +- The protocol is BLOCKED until all required consultations are complete + +**Consultation Checkpoints**: +- **Specification**: After initial draft, after human comments +- **Planning**: After initial plan, after human review +- **Implementation**: After code implementation +- **Defending**: After test creation +- **Evaluation**: Before marking phase complete +- **Review**: After review document + +## Overview +SPIR is a structured development protocol that emphasizes specification-driven development with iterative implementation and continuous review. It builds upon the DAPPER methodology with a focus on context-first development and multi-agent collaboration. + +**The SPIR Model**: +- **S - Specify**: Write specification with 3-way review → Gate: `spec-approval` +- **P - Plan**: Write implementation plan with 3-way review → Gate: `plan-approval` +- **I - Implement**: Execute each plan phase with build-verify cycle (one cycle per phase) +- **R - Review**: Final review and PR preparation with 3-way review + +Each phase follows a build-verify loop: build the artifact, then verify with 3-way consultation (Gemini, Codex, Claude). + +**Core Principle**: Each feature is tracked through exactly THREE documents - a specification, a plan, and a review with lessons learned - all sharing the same filename and sequential identifier. + +## When to Use SPIR + +### Use SPIR for: +- New feature development +- Architecture changes +- Complex refactoring +- System design decisions +- API design and implementation +- Performance optimization initiatives + +### Skip SPIR for: +- Simple bug fixes (< 10 lines) +- Documentation updates +- Configuration changes +- Dependency updates +- Emergency hotfixes (but do a lightweight retrospective after) + +## Protocol Phases + +### S - Specify (Collaborative Design Exploration) + +**Purpose**: Thoroughly explore the problem space and solution options before committing to an approach. + +**Workflow Overview**: +1. User provides a prompt describing what they want built +2. Agent generates initial specification document +3. **COMMIT**: "Initial specification draft" +4. Multi-agent review (GPT-5 and Gemini Pro) +5. Agent updates spec with multi-agent feedback +6. **COMMIT**: "Specification with multi-agent review" +7. Human reviews and provides comments for changes +8. Agent makes changes and lists what was modified +9. **COMMIT**: "Specification with user feedback" +10. Multi-agent review of updated document +11. Final updates based on second review +12. **COMMIT**: "Final approved specification" +13. Iterate steps 7-12 until user approves and says to proceed to planning + +**Important**: Keep documentation minimal - use only THREE core files with the same name: +- `specs/####-descriptive-name.md` - The specification +- `plans/####-descriptive-name.md` - The implementation plan +- `reviews/####-descriptive-name.md` - Review and lessons learned (created during Review phase) + +**Process**: +1. **Clarifying Questions** (ALWAYS START HERE) + - Ask the user/stakeholder questions to understand the problem + - Probe for hidden requirements and constraints + - Understand the business context and goals + - Identify what's in scope and out of scope + - Continue asking until the problem is crystal clear + +2. **Problem Analysis** + - Clearly articulate the problem being solved + - Identify stakeholders and their needs + - Document current state and desired state + - List assumptions and constraints + +3. **Solution Exploration** + - Generate multiple solution approaches (as many as appropriate) + - For each approach, document: + - Technical design + - Trade-offs (pros/cons) + - Estimated complexity + - Risk assessment + +4. **Open Questions** + - List all uncertainties that need resolution + - Categorize as: + - Critical (blocks progress) + - Important (affects design) + - Nice-to-know (optimization) + +5. **Success Criteria** + - Define measurable acceptance criteria + - Include performance requirements + - Specify quality metrics + - Document test scenarios + +6. **Expert Consultation (DEFAULT - MANDATORY)** + - **First Consultation** (after initial draft): + - MUST consult GPT-5 AND Gemini Pro + - Focus: Problem clarity, solution completeness, missing requirements + - Update specification with ALL feedback from both models + - Document changes in "Consultation Log" section of the spec + - **Second Consultation** (after human comments): + - MUST consult GPT-5 AND Gemini Pro again + - Focus: Validate changes, ensure alignment + - Final specification update with both models' input + - Update "Consultation Log" with new feedback + + **Note**: Only skip if user explicitly requested "without multi-agent consultation" + +**⚠️ BLOCKING**: Cannot proceed without BOTH consultations (unless explicitly disabled) + +**Output**: Single specification document in `codev/specs/####-descriptive-name.md` +- All consultation feedback incorporated directly into this document +- Include a "Consultation Log" section summarizing key feedback and changes +- Version control captures evolution through commits +**Template**: `templates/spec.md` +**Review Required**: Yes - Human approval AFTER consultations + +### P - Plan (Structured Decomposition) + +**Purpose**: Transform the approved specification into an executable roadmap with clear phases. + +**⚠️ CRITICAL: No Time Estimates in the AI Age** +- **NEVER include time estimates** (hours, days, weeks, story points) +- AI-driven development makes traditional time estimates meaningless +- Delivery speed depends on iteration cycles, not calendar time +- Focus on logical dependencies and phase ordering instead +- Measure progress by completed phases, not elapsed time +- The only valid metrics are: "done" or "not done" + +**Workflow Overview**: +1. Agent creates initial plan document +2. **COMMIT**: "Initial plan draft" +3. Multi-agent review (GPT-5 and Gemini Pro) +4. Agent updates plan with multi-agent feedback +5. **COMMIT**: "Plan with multi-agent review" +6. User reviews and requests modifications +7. Agent updates plan based on user feedback +8. **COMMIT**: "Plan with user feedback" +9. Multi-agent review of updated plan +10. Final updates based on second review +11. **COMMIT**: "Final approved plan" +12. Iterate steps 6-11 until agreement is reached + +**Phase Design Goals**: +Each phase should be: +- A separate piece of work that can be checked in as a unit +- A complete set of functionality +- Self-contained and independently valuable + +**Process**: +1. **Phase Definition** + - Break work into logical phases + - Each phase must: + - Have a clear, single objective + - Be independently testable + - Deliver observable value + - Be a complete unit that can be committed + - End with evaluation discussion and single commit + - Note dependencies inline, for example: + ```markdown + Phase 2: API Endpoints + - Depends on: Phase 1 (Database Schema) + - Objective: Create /users and /todos endpoints + - Evaluation: Test coverage, API design review, performance check + - Commit: Will create single commit after user approval + ``` + +2. **Success Metrics** + - Define "done" for each phase + - Include test coverage requirements + - Specify performance benchmarks + - Document acceptance tests + +3. **Expert Review (DEFAULT - MANDATORY)** + - **First Consultation** (after plan creation): + - MUST consult GPT-5 AND Gemini Pro + - Focus: Feasibility, phase breakdown, completeness + - Update plan with ALL feedback from both models + - **Second Consultation** (after human review): + - MUST consult GPT-5 AND Gemini Pro again + - Focus: Validate adjustments, confirm approach + - Final plan refinement with both models' input + + **Note**: Only skip if user explicitly requested "without multi-agent consultation" + +**⚠️ BLOCKING**: Cannot proceed without BOTH consultations (unless explicitly disabled) + +**Output**: Single plan document in `codev/plans/####-descriptive-name.md` +- Same filename as specification, different directory +- All consultation feedback incorporated directly +- Include phase status tracking within this document +- **DO NOT include time estimates** - Focus on deliverables and dependencies, not hours/days +- Version control captures evolution through commits +**Template**: `templates/plan.md` +**Review Required**: Yes - Technical lead approval AFTER consultations + +### I - Implement (Per Plan Phase) + +Execute for each phase in the plan. Each phase follows a build-verify cycle. + +**CRITICAL PRECONDITION**: Before starting any phase, verify the previous phase was committed to git. No phase can begin without the prior phase's commit. + +**Build-Verify Cycle Per Phase**: +1. **Build** - Implement code and tests for this phase +2. **Verify** - 3-way consultation (Gemini, Codex, Claude) +3. **Iterate** - Address feedback until verification passes +4. **Commit** - Single atomic commit for the phase (MANDATORY before next phase) +5. **Proceed** - Move to next phase only after commit + +**Handling Failures**: +- If verification reveals gaps → iterate and fix +- If fundamental plan flaws found → mark phase as `blocked` and revise plan + +**Commit Requirements**: +- Each phase MUST end with a git commit before proceeding +- Commit message format: `[Spec ####][Phase: name] type: Description` +- No work on the next phase until current phase is committed +- If changes are needed after commit, create a new commit with fixes + +#### I - Implement (Build with Discipline) + +**Purpose**: Transform the plan into working code with high quality standards. + +**Precondition**: Previous phase must be committed (verify with `git log`) + +**Requirements**: +1. **Pre-Implementation** + - Verify previous phase is committed to git + - Review the phase plan and success criteria + - Set up the development environment + - Create feature branch following naming convention + - Document any plan deviations immediately + +2. **During Implementation** + - Write self-documenting code + - Follow project style guide strictly + - Implement incrementally with frequent commits + - Each commit must: + - Be atomic (single logical change) + - Include descriptive message + - Reference the phase + - Pass basic syntax checks + +3. **Code Quality Standards** + - No commented-out code + - No debug prints in final code + - Handle all error cases explicitly + - Include necessary logging + - Follow security best practices + +4. **Documentation Requirements** + - Update API documentation + - Add inline comments for complex logic + - Update README if needed + - Document configuration changes + +**Evidence Required**: +- Link to commits +- Code review approval (if applicable) +- No linting errors +- CI pipeline pass link (build/test/lint) + +**Expert Consultation (DEFAULT - MANDATORY)**: +- MUST consult BOTH GPT-5 AND Gemini Pro after implementation +- Focus: Code quality, patterns, security, best practices +- Update code based on feedback from BOTH models before proceeding +- Only skip if user explicitly disabled multi-agent consultation + +#### D - Defend (Write Comprehensive Tests) + +**Purpose**: Create comprehensive automated tests that safeguard intended behavior and prevent regressions. + +**CRITICAL**: Tests must be written IMMEDIATELY after implementation, NOT retroactively at the end of all phases. This is MANDATORY. + +**Requirements**: +1. **Defensive Test Creation** + - Write unit tests for all new functions + - Create integration tests for feature flows + - Develop edge case coverage + - Build error condition tests + - Establish performance benchmarks + +2. **Test Validation** (ALL MANDATORY) + - All new tests must pass + - All existing tests must pass + - No reduction in overall coverage + - Performance benchmarks met + - Security scans pass + - **Avoid Overmocking**: + - Test behavior, not implementation details + - Prefer integration tests over unit tests with heavy mocking + - Only mock external dependencies (APIs, databases, file systems) + - Never mock the system under test itself + - Use real implementations for internal module boundaries + +3. **Test Suite Documentation** + - Document test scenarios + - Explain complex test setups + - Note any flaky tests + - Record performance baselines + +**Evidence Required**: +- Test execution logs +- Coverage report (show no reduction) +- Performance test results (if applicable per spec) +- Security scan results (if configured) +- CI test run link with artifacts + +**Expert Consultation (DEFAULT - MANDATORY)**: +- MUST consult BOTH GPT-5 AND Gemini Pro for test defense review +- Focus: Test coverage completeness, edge cases, defensive patterns, test strategy +- Write additional defensive tests based on feedback from BOTH models +- Share their feedback during the Evaluation discussion +- Only skip if user explicitly disabled multi-agent consultation + +#### E - Evaluate (Assess Objectively) + +**Purpose**: Verify the implementation fully satisfies the phase requirements and maintains system quality. This is where the critical discussion happens before committing the phase. + +**Requirements**: +1. **Functional Evaluation** + - All acceptance criteria met + - User scenarios work as expected + - Edge cases handled properly + - Error messages are helpful + +2. **Non-Functional Evaluation** + - Performance requirements satisfied + - Security standards maintained + - Code maintainability assessed + - Technical debt documented + +3. **Deviation Analysis** + - Document any changes from plan + - Explain reasoning for changes + - Assess impact on other phases + - Update future phases if needed + - **Overmocking Check** (MANDATORY): + - Verify tests focus on behavior, not implementation + - Ensure at least one integration test per critical path + - Check that internal module boundaries use real implementations + - Confirm mocks are only used for external dependencies + - Tests should survive refactoring that preserves behavior + +4. **Expert Consultation Before User Evaluation** (MANDATORY - NO EXCEPTIONS) + - Get initial feedback from experts + - Make ALL necessary fixes based on feedback + - **CRITICAL**: Get FINAL approval from ALL consulted experts on the FIXED version + - Only proceed to user evaluation after ALL experts approve + - If any expert says "not quite" or has concerns, fix them FIRST + +5. **Evaluation Discussion with User** (ONLY AFTER EXPERT APPROVAL) + - Present to user: "Phase X complete. Here's what was built: [summary]" + - Share test results and coverage metrics + - Share that ALL experts have given final approval + - Ask: "Any changes needed before I commit this phase?" + - Incorporate user feedback if requested + - Get explicit approval to proceed + +6. **Phase Commit** (MANDATORY - NO EXCEPTIONS) + - Create single atomic commit for the entire phase + - Commit message: `[Spec ####][Phase: name] type: Description` + - Update the plan document marking this phase as complete + - Push all changes to version control + - Document any deviations or decisions in the plan + - **CRITICAL**: Next phase CANNOT begin until this commit is complete + - Verify commit with `git log` before proceeding + +7. **Final Verification** + - Confirm all expert feedback was addressed + - Verify all tests pass + - Check that documentation is updated + - Ensure no outstanding concerns from experts or user + +**Evidence Required**: +- Evaluation checklist completed +- Test results and coverage report +- Expert review notes from GPT-5 and Gemini Pro +- User approval from evaluation discussion +- Updated plan document with: + - Phase marked complete + - Evaluation discussion summary + - Any deviations noted +- Git commit for this phase +- Final CI run link after all fixes + +## 📋 PHASE COMPLETION CHECKLIST (MANDATORY BEFORE NEXT PHASE) + +**⚠️ STOP: DO NOT PROCEED TO NEXT PHASE UNTIL ALL ITEMS ARE ✅** + +### Before Starting ANY Phase: +- [ ] Previous phase is committed to git (verify with `git log`) +- [ ] Plan document shows previous phase as `completed` +- [ ] No outstanding issues from previous phase + +### After Implement Phase: +- [ ] All code for this phase is complete +- [ ] Code follows project style guide +- [ ] No commented-out code or debug prints +- [ ] Error handling is implemented +- [ ] Documentation is updated (if needed) +- [ ] Expert consultation completed (GPT-5 + Gemini Pro) +- [ ] Expert feedback has been addressed + +### After Defend Phase: +- [ ] Unit tests written for all new functions +- [ ] Integration tests written for critical paths +- [ ] Edge cases have test coverage +- [ ] All new tests are passing +- [ ] All existing tests still pass +- [ ] No reduction in code coverage +- [ ] Overmocking check completed (tests focus on behavior) +- [ ] Expert consultation on tests completed +- [ ] Test feedback has been addressed + +### After Evaluate Phase: +- [ ] All acceptance criteria from spec are met +- [ ] Performance requirements satisfied +- [ ] Security standards maintained +- [ ] Expert consultation shows FINAL approval +- [ ] User evaluation discussion completed +- [ ] User has given explicit approval to proceed +- [ ] Plan document updated with phase status +- [ ] Phase commit created with proper message format +- [ ] Commit pushed to version control +- [ ] Commit verified with `git log` + +### ❌ PHASE BLOCKERS (Fix Before Proceeding): +- Any failing tests +- Unaddressed expert feedback +- Missing user approval +- Uncommitted changes +- Incomplete documentation +- Coverage reduction + +**REMINDER**: Each phase is atomic. You cannot start the next phase until the current phase is fully complete, tested, evaluated, and committed. + +### R - Review/Refine/Revise (Continuous Improvement) + +**Purpose**: Ensure overall coherence, capture learnings, improve the methodology, and perform systematic review. + +**Precondition**: All implementation phases must be committed (verify with `git log --oneline | grep "\[Phase"`) + +**Process**: +1. **Comprehensive Review** + - Verify all phases have been committed to git + - Compare final implementation to original specification + - Assess overall architecture impact + - Review code quality across all changes + - Validate documentation completeness + +2. **Refinement Actions** + - Refactor code for clarity if needed + - Optimize performance bottlenecks + - Improve test coverage gaps + - Enhance documentation + +3. **Update Architecture Documentation** + - Update `codev/resources/arch.md` with new modules, utilities, or architectural changes + - Follow guidance in MAINTAIN protocol's "Update arch.md" task for structure and standards + - Ensure arch.md reflects current codebase state + +4. **Revision Requirements** (MANDATORY) + - Update README.md with any new features or changes + - Update AGENTS.md and CLAUDE.md with protocol improvements from lessons learned + - Update specification and plan documents with final status + - Revise architectural diagrams if needed + - Update API documentation + - Modify deployment guides as necessary + - **CRITICAL**: Update this protocol document based on lessons learned + +5. **Systematic Issue Review** (MANDATORY) + - Review entire project for systematic issues: + - Repeated problems across phases + - Process bottlenecks or inefficiencies + - Missing documentation patterns + - Technical debt accumulation + - Testing gaps or quality issues + - Document systematic findings in lessons learned + - Create action items for addressing systematic issues + +6. **Lessons Learned** (MANDATORY) + - What went well? + - What was challenging? + - What would you do differently? + - What methodology improvements are needed? + - What systematic issues were identified? + +7. **Methodology Evolution** + - Propose process improvements based on lessons + - Update protocol documents with improvements + - Update templates if needed + - Share learnings with team + - Document in `codev/reviews/` + - **Important**: This protocol should evolve based on each project's learnings + +**Output**: +- Single review document in `codev/reviews/####-descriptive-name.md` +- Same filename as spec/plan, captures review and learnings from this feature +- Methodology improvement proposals (update protocol if needed) + +**Review Required**: Yes - Team retrospective recommended + +## File Naming Conventions + +### Specifications and Plans +Format: `####-descriptive-name.md` +- Use sequential numbering (1, 2, etc.) +- Same filename in both `specs/` and `plans/` directories +- Example: `1-user-authentication.md` + +## Status Tracking + +Status is tracked at the **phase level** within plan documents, not at the document level. + +Each phase in a plan should have a status: +- `pending`: Not started +- `in-progress`: Currently being worked on +- `completed`: Phase finished and tested +- `blocked`: Cannot proceed due to external factors + +## Git Integration + +### Commit Message Format + +For specification/plan documents: +``` +[Spec ####] : +``` + +Examples: +``` +[Spec 1] Initial specification draft +[Spec 1] Specification with multi-agent review +[Spec 1] Specification with user feedback +[Spec 1] Final approved specification +``` + +For implementation: +``` +[Spec ####][Phase: ] : + + +``` + +Example: +``` +[Spec 1][Phase: user-auth] feat: Add password hashing service + +Implements bcrypt-based password hashing with configurable rounds +``` + +### Branch Naming +``` +spir/####-/ +``` + +Example: +``` +spir/1-user-authentication/database-schema +``` + + +## Best Practices + +### During Specification +- Use clear, unambiguous language +- Include concrete examples +- Define measurable success criteria +- Link to relevant references + +### During Planning +- Keep phases small and focused +- Ensure each phase delivers value +- Note phase dependencies inline (no formal dependency mapping needed) +- Include rollback strategies + +### During Implementation +- Follow the plan but document deviations +- Maintain test coverage +- Keep commits atomic and well-described +- Update documentation as you go + +### During Review +- Check against original specification +- Document lessons learned +- Propose methodology improvements +- Update estimates for future work + +## Templates + +Templates for each phase are available in the `templates/` directory: +- `spec.md` - Specification template +- `plan.md` - Planning template (includes phase status tracking) +- `review.md` - Review and lessons learned template + +**Remember**: Only create THREE documents per feature - spec, plan, and review with the same filename in different directories. + +## Protocol Evolution + +This protocol can be customized per project: +1. Fork the protocol directory +2. Modify templates and processes +3. Document changes in `protocol-changes.md` +4. Share improvements back to the community \ No newline at end of file diff --git a/codev/protocols/spir/templates/plan.md b/codev/protocols/spir/templates/plan.md new file mode 100644 index 0000000..8311998 --- /dev/null +++ b/codev/protocols/spir/templates/plan.md @@ -0,0 +1,204 @@ +# Plan: [Title] + +## Metadata +- **ID**: plan-[YYYY-MM-DD]-[short-name] +- **Status**: draft +- **Specification**: [Link to codev/specs/spec-file.md] +- **Created**: [YYYY-MM-DD] + +## Executive Summary +[Brief overview of the implementation approach chosen and why. Reference the specification's selected approach.] + +## Success Metrics +[Copy from specification and add implementation-specific metrics] +- [ ] All specification criteria met +- [ ] Test coverage >90% +- [ ] Performance benchmarks achieved +- [ ] Zero critical security issues +- [ ] Documentation complete + +## Phases (Machine Readable) + + + +```json +{ + "phases": [ + {"id": "phase_1", "title": "Phase 1 Title Here"}, + {"id": "phase_2", "title": "Phase 2 Title Here"}, + {"id": "phase_3", "title": "Phase 3 Title Here"} + ] +} +``` + +## Phase Breakdown + +### Phase 1: [Descriptive Name] +**Dependencies**: None + +#### Objectives +- [Clear, single objective for this phase] +- [What value does this phase deliver?] + +#### Deliverables +- [ ] [Specific deliverable 1] +- [ ] [Specific deliverable 2] +- [ ] [Tests for this phase] +- [ ] [Documentation updates] + +#### Implementation Details +[Specific technical approach for this phase. Include: +- Key files/modules to create or modify +- Architectural decisions +- API contracts +- Data models] + +#### Acceptance Criteria +- [ ] [Testable criterion 1] +- [ ] [Testable criterion 2] +- [ ] All tests pass +- [ ] Code review completed + +#### Test Plan +- **Unit Tests**: [What to test] +- **Integration Tests**: [What to test] +- **Manual Testing**: [Scenarios to verify] + +#### Rollback Strategy +[How to revert this phase if issues arise] + +#### Risks +- **Risk**: [Specific risk for this phase] + - **Mitigation**: [How to address] + +--- + +### Phase 2: [Descriptive Name] +**Dependencies**: Phase 1 + +[Repeat structure for each phase] + +--- + +### Phase 3: [Descriptive Name] +**Dependencies**: Phase 2 + +[Continue for all phases] + +## Dependency Map +``` +Phase 1 ──→ Phase 2 ──→ Phase 3 + ↓ + Phase 4 (optional) +``` + +## Resource Requirements +### Development Resources +- **Engineers**: [Expertise needed] +- **Environment**: [Dev/staging requirements] + +### Infrastructure +- [Database changes] +- [New services] +- [Configuration updates] +- [Monitoring additions] + +## Integration Points +### External Systems +- **System**: [Name] + - **Integration Type**: [API/Database/Message Queue] + - **Phase**: [Which phase needs this] + - **Fallback**: [What if unavailable] + +### Internal Systems +[Repeat structure] + +## Risk Analysis +### Technical Risks +| Risk | Probability | Impact | Mitigation | Owner | +|------|------------|--------|------------|-------| +| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | + +### Schedule Risks +| Risk | Probability | Impact | Mitigation | Owner | +|------|------------|--------|------------|-------| +| [Risk 1] | L/M/H | L/M/H | [Strategy] | [Name] | + +## Validation Checkpoints +1. **After Phase 1**: [What to validate] +2. **After Phase 2**: [What to validate] +3. **Before Production**: [Final checks] + +## Monitoring and Observability +### Metrics to Track +- [Metric 1: Description and threshold] +- [Metric 2: Description and threshold] + +### Logging Requirements +- [What to log and at what level] +- [Retention requirements] + +### Alerting +- [Alert condition and severity] +- [Who to notify] + +## Documentation Updates Required +- [ ] API documentation +- [ ] Architecture diagrams +- [ ] Runbooks +- [ ] User guides +- [ ] Configuration guides + +## Post-Implementation Tasks +- [ ] Performance validation +- [ ] Security audit +- [ ] Load testing +- [ ] User acceptance testing +- [ ] Monitoring validation + +## Expert Review +**Date**: [YYYY-MM-DD] +**Model**: [Model consulted] +**Key Feedback**: +- [Feasibility assessment] +- [Missing considerations] +- [Risk identification] +- [Alternative suggestions] + +**Plan Adjustments**: +- [How the plan was modified based on feedback] + +## Approval +- [ ] Technical Lead Review +- [ ] Engineering Manager Approval +- [ ] Resource Allocation Confirmed +- [ ] Expert AI Consultation Complete + +## Change Log +| Date | Change | Reason | Author | +|------|--------|--------|--------| +| [Date] | [What changed] | [Why] | [Who] | + +## Notes +[Additional context, assumptions, or considerations] + +--- + +## Amendment History + +This section tracks all TICK amendments to this plan. TICKs modify both the spec and plan together as an atomic unit. + + + + \ No newline at end of file diff --git a/codev/protocols/spir/templates/review.md b/codev/protocols/spir/templates/review.md new file mode 100644 index 0000000..eaaf682 --- /dev/null +++ b/codev/protocols/spir/templates/review.md @@ -0,0 +1,120 @@ +# Review: [Feature/Project Name] + +## Summary + +[1-3 sentences: what was built, how many phases, net outcome.] + +## Spec Compliance + +- [x] AC1: [Description] (Phase N) +- [x] AC2: [Description] (Phase N) +- [ ] ACn: [Not met — reason] + +## Deviations from Plan + +- **Phase N**: [What changed and why] + +## Key Metrics + +- **Commits**: [N] on the branch +- **Tests**: [N] passing ([N] existing + [N] new) +- **Files created**: [list] +- **Files deleted**: [list] +- **Net LOC impact**: [+/-N lines] + +## Timelog + +All times [timezone], [date range]. + +| Time | Event | +|------|-------| +| HH:MM | First commit: [description] | +| HH:MM | [Phase/milestone] | +| — | **GATE: [gate-name]** (human approval required) | +| HH:MM | Implementation begins | +| HH:MM | Phase N complete after N iterations | +| HH:MM | **GATE: pr** | + +### Autonomous Operation + +| Period | Duration | Activity | +|--------|----------|----------| +| Spec + Plan | ~Nm | [Summary] | +| Human gate wait | ~Nh Nm | Idle — waiting for approval | +| Implementation → PR | ~Nh Nm | N phases, N consultation rounds | + +**Total wall clock** (first commit to pr): **Xh Ym** +**Total autonomous work time** (excluding gate waits): **~Xh Ym** +**Context window resets**: [N] (resumed automatically / required manual restart) + +## Consultation Iteration Summary + +[N] consultation files produced ([N] rounds x [N] models). [N] APPROVE, [N] REQUEST_CHANGES, [N] COMMENT. + +| Phase | Iters | Who Blocked | What They Caught | +|-------|-------|-------------|------------------| +| Specify | N | [Model] | [Brief description] | +| Plan | N | [Model] | [Brief description] | +| Phase 1 | N | [Model] | [Brief description] | +| Phase N | N | [Model] | [Brief description] | +| Review | N | [Model] | [Brief description] | + +**Most frequent blocker**: [Model] — blocked in N of N rounds, focused on: [pattern]. + +### Avoidable Iterations + +Iterations that could have been prevented with better builder behavior: + +1. **[Pattern]**: [Specific thing the builder should have done without needing reviewer feedback. E.g., "Run exhaustive grep before claiming all instances fixed."] + +2. **[Pattern]**: [Another avoidable iteration pattern.] + +## Consultation Feedback + +[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."] + +### [Phase] Phase (Round N) + +#### Gemini +- **Concern**: [Summary of concern] + - **Addressed**: [What was changed] + +#### Codex +- **Concern**: [Summary of concern] + - **Rebutted**: [Why current approach is correct] + +#### Claude +- No concerns raised (APPROVE) + +## Lessons Learned + +### What Went Well +- [Specific positive observation — what worked and why] + +### Challenges Encountered +- **[Challenge]**: [How it was resolved. How many iterations it cost.] + +### What Would Be Done Differently +- [Actionable improvement for future builders] + +## Architecture Updates + +[What was added/changed in `codev/resources/arch.md`, or why no changes were needed.] + +- Updated: [section name] — [what was added/changed] +- Or: "No architecture updates needed — [brief reason]" + +## Lessons Learned Updates + +[What was added/changed in `codev/resources/lessons-learned.md`, or why no changes were needed.] + +- Added: [category] — [lesson summary] +- Or: "No lessons learned updates needed — [brief reason]" + +## Technical Debt + +- [Any shortcuts taken or inconsistencies introduced] + +## Follow-up Items + +- [Items identified for future work, outside this spec's scope] diff --git a/codev/protocols/spir/templates/spec.md b/codev/protocols/spir/templates/spec.md new file mode 100644 index 0000000..03c1731 --- /dev/null +++ b/codev/protocols/spir/templates/spec.md @@ -0,0 +1,182 @@ +# Specification: [Title] + + + +## Metadata +- **ID**: spec-[YYYY-MM-DD]-[short-name] +- **Status**: draft +- **Created**: [YYYY-MM-DD] + +## Clarifying Questions Asked + +[List the questions you asked to understand the problem better and the responses received. This shows the discovery process.] + +## Problem Statement +[Clearly articulate the problem being solved. Include context about why this is important, who is affected, and what the current pain points are.] + +## Current State +[Describe how things work today. What are the limitations? What workarounds exist? Include specific examples.] + +## Desired State +[Describe the ideal solution. How should things work after implementation? What specific improvements will users see?] + +## Stakeholders +- **Primary Users**: [Who will directly use this feature?] +- **Secondary Users**: [Who else is affected?] +- **Technical Team**: [Who will implement and maintain this?] +- **Business Owners**: [Who has decision authority?] + +## Success Criteria +- [ ] [Specific, measurable criterion 1] +- [ ] [Specific, measurable criterion 2] +- [ ] [Specific, measurable criterion 3] +- [ ] All tests pass with >90% coverage +- [ ] Performance benchmarks met (specify below) +- [ ] Documentation updated + +## Constraints +### Technical Constraints +- [Existing system limitations] +- [Technology stack requirements] +- [Integration points] + +### Business Constraints +- [Timeline requirements] +- [Budget considerations] +- [Compliance requirements] + +## Assumptions +- [List assumptions being made] +- [Include dependencies on other work] +- [Note any prerequisites] + +## Solution Approaches + +### Approach 1: [Name] +**Description**: [Brief overview of this approach] + +**Pros**: +- [Advantage 1] +- [Advantage 2] + +**Cons**: +- [Disadvantage 1] +- [Disadvantage 2] + +**Estimated Complexity**: [Low/Medium/High] +**Risk Level**: [Low/Medium/High] + +### Approach 2: [Name] +[Repeat structure for additional approaches] + +[Add as many approaches as appropriate for the problem] + +## Open Questions + +### Critical (Blocks Progress) +- [ ] [Question that must be answered before proceeding] + +### Important (Affects Design) +- [ ] [Question that influences technical decisions] + +### Nice-to-Know (Optimization) +- [ ] [Question that could improve the solution] + +## Performance Requirements +- **Response Time**: [e.g., <200ms p95] +- **Throughput**: [e.g., 1000 requests/second] +- **Resource Usage**: [e.g., <500MB memory] +- **Availability**: [e.g., 99.9% uptime] + +## Security Considerations +- [Authentication requirements] +- [Authorization model] +- [Data privacy concerns] +- [Audit requirements] + +## Test Scenarios +### Functional Tests +1. [Scenario 1: Happy path] +2. [Scenario 2: Edge case] +3. [Scenario 3: Error condition] + +### Non-Functional Tests +1. [Performance test scenario] +2. [Security test scenario] +3. [Load test scenario] + +## Dependencies +- **External Services**: [List any external APIs or services] +- **Internal Systems**: [List internal dependencies] +- **Libraries/Frameworks**: [List required libraries] + +## References +- [Link to relevant documentation in codev/ref/] +- [Link to related specifications] +- [Link to architectural diagrams] +- [Link to research materials] + +## Risks and Mitigation +| Risk | Probability | Impact | Mitigation Strategy | +|------|------------|--------|-------------------| +| [Risk 1] | Low/Med/High | Low/Med/High | [How to address] | +| [Risk 2] | Low/Med/High | Low/Med/High | [How to address] | + +## Expert Consultation + +**Date**: [YYYY-MM-DD] +**Models Consulted**: [e.g., GPT-5 and Gemini Pro] +**Sections Updated**: +- [Section name]: [Brief description of change based on consultation] +- [Section name]: [Brief description of change based on consultation] + +Note: All consultation feedback has been incorporated directly into the relevant sections above. + +## Approval +- [ ] Technical Lead Review +- [ ] Product Owner Review +- [ ] Stakeholder Sign-off +- [ ] Expert AI Consultation Complete + +## Notes +[Any additional context or considerations not covered above] + +--- + +## Amendments + +This section tracks all TICK amendments to this specification. TICKs are lightweight changes that refine an existing spec rather than creating a new one. + + + + \ No newline at end of file diff --git a/codev/protocols/tick/builder-prompt.md b/codev/protocols/tick/builder-prompt.md new file mode 100644 index 0000000..ee92d34 --- /dev/null +++ b/codev/protocols/tick/builder-prompt.md @@ -0,0 +1,65 @@ +# {{protocol_name}} Builder ({{mode}} mode) + +You are implementing {{input_description}}. + +{{#if mode_soft}} +## Mode: SOFT +You are running in SOFT mode. This means: +- You follow the TICK protocol yourself (no porch orchestration) +- The architect monitors your work and verifies you're adhering to the protocol +- Run consultations manually when the protocol calls for them +- You have flexibility in execution, but must stay compliant with the protocol +{{/if}} + +{{#if mode_strict}} +## Mode: STRICT +You are running in STRICT mode. This means: +- Porch orchestrates your work +- Run: `porch next` to get your next tasks +- Follow porch signals and gate approvals + +### ABSOLUTE RESTRICTIONS (STRICT MODE) +- **NEVER edit `status.yaml` directly** — only porch commands may modify project state +- **NEVER call `porch approve` without explicit human approval** — only run it after the architect says to +- **NEVER skip the 3-way review** — always follow porch next → porch done cycle +{{/if}} + +## Protocol +Follow the TICK protocol: `codev/protocols/tick/protocol.md` + +TICK is for amendments to existing SPIR specifications. You will: +1. Identify the target spec to amend +2. Update the spec with the amendment +3. Update the plan +4. Implement the changes +5. Defend with tests +6. Create review + +{{#if spec}} +## Target Spec +The spec to amend is at: `{{spec.path}}` +{{/if}} + +{{#if plan}} +## Target Plan +The plan to amend is at: `{{plan.path}}` +{{/if}} + +{{#if task}} +## Amendment Description +{{task_text}} +{{/if}} + +## Handling Flaky Tests + +If you encounter **pre-existing flaky tests** (intermittent failures unrelated to your changes): +1. **DO NOT** edit `status.yaml` to bypass checks +2. **DO NOT** skip porch checks or use any workaround to avoid the failure +3. **DO** mark the test as skipped with a clear annotation (e.g., `it.skip('...') // FLAKY: skipped pending investigation`) +4. **DO** document each skipped flaky test in your review under a `## Flaky Tests` section +5. Commit the skip and continue with your work + +## Getting Started +1. Read the TICK protocol thoroughly +2. Identify what needs to change in the existing spec +3. Follow the amendment workflow diff --git a/codev/protocols/tick/consult-types/impl-review.md b/codev/protocols/tick/consult-types/impl-review.md new file mode 100644 index 0000000..de01b8d --- /dev/null +++ b/codev/protocols/tick/consult-types/impl-review.md @@ -0,0 +1,72 @@ +# Implementation Review Prompt + +## Context +You are reviewing implementation work during the Implement phase. A builder has completed a plan phase and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan. + +## CRITICAL: Verify Before Flagging + +Before requesting changes for missing configuration, incorrect patterns, or framework issues: +1. **Check `package.json`** for actual dependency versions — framework conventions change between major versions +2. **Read the actual config files** (or confirm their deliberate absence) before flagging missing configs +3. **Do not assume** your training data reflects the version in use — verify against project files +4. If "Previous Iteration Context" is provided, read it carefully before re-raising concerns that were already disputed + +## Focus Areas + +1. **Spec Adherence** + - Does the implementation fulfill the spec requirements for this phase? + - Are acceptance criteria met? + +2. **Code Quality** + - Is the code readable and maintainable? + - Are there obvious bugs or issues? + - Are error cases handled appropriately? + +3. **Test Coverage** + - Are the tests adequate for this phase? + - Do tests cover the main paths AND edge cases? + +4. **Plan Alignment** + - Does the implementation follow the plan? + - Are there plan items skipped or partially completed? + +5. **UX Verification** (if spec has UX requirements) + - Does the actual user experience match what the spec describes? + - If spec says "async" or "non-blocking", is it actually async? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Phase is complete, builder can proceed +- `REQUEST_CHANGES`: Issues that must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but note feedback + +## Scoping (Multi-Phase Plans) + +When the implementation plan has multiple phases (e.g., scaffolding, landing, media_rtl): +- **ONLY review work belonging to the current plan phase** +- The query will specify which phase you are reviewing +- Do NOT request changes for functionality scheduled in later phases +- Do NOT flag missing features that are out of scope for this phase +- If unsure whether something belongs to this phase, check the plan file + +## Notes + +- This is a phase-level review, not the final PR review +- Focus on "does this phase work" not "is the whole feature done" +- If referencing line numbers, use `file:line` format +- The builder needs actionable feedback to continue diff --git a/codev/protocols/tick/consult-types/plan-review.md b/codev/protocols/tick/consult-types/plan-review.md new file mode 100644 index 0000000..585085d --- /dev/null +++ b/codev/protocols/tick/consult-types/plan-review.md @@ -0,0 +1,59 @@ +# Plan Review Prompt + +## Context +You are reviewing an implementation plan during the Plan phase. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it. + +## Focus Areas + +1. **Spec Coverage** + - Does the plan address all requirements in the spec? + - Are there spec requirements not covered by any phase? + - Are there phases that go beyond the spec scope? + +2. **Phase Breakdown** + - Are phases appropriately sized (not too large or too small)? + - Is the sequence logical (dependencies respected)? + - Can each phase be completed and committed independently? + +3. **Technical Approach** + - Is the implementation approach sound? + - Are the right files/modules being modified? + - Are there obvious better approaches being missed? + +4. **Testability** + - Does each phase have clear test criteria? + - Will the Defend step (writing tests) be feasible? + - Are edge cases from the spec addressable? + +5. **Risk Assessment** + - Are there potential blockers not addressed? + - Are dependencies on other systems identified? + - Is the plan realistic given constraints? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Plan is ready for human review +- `REQUEST_CHANGES`: Significant issues with approach or coverage +- `COMMENT`: Minor suggestions, plan is workable but could improve + +## Notes + +- The spec has already been approved - don't re-litigate spec decisions +- Focus on the quality of the plan as a guide for builders +- Consider: Would a builder be able to follow this plan successfully? +- If referencing existing code, verify file paths seem accurate diff --git a/codev/protocols/tick/consult-types/pr-review.md b/codev/protocols/tick/consult-types/pr-review.md new file mode 100644 index 0000000..048c23f --- /dev/null +++ b/codev/protocols/tick/consult-types/pr-review.md @@ -0,0 +1,72 @@ +# PR Ready Review Prompt + +## Context +You are performing a final self-check during the Review phase. The builder has completed all implementation phases and is about to create a PR. This is the last check before the work goes to the architect for integration review. + +## Focus Areas + +1. **Completeness** + - Are all spec requirements implemented? + - Are all plan phases complete? + - Is the review document written (`codev/reviews/XXXX-name.md`)? + - Are all commits properly formatted (`[Spec XXXX][Phase]`)? + +2. **Test Status** + - Do all tests pass? + - Is test coverage adequate for the changes? + - Are there any skipped or flaky tests? + +3. **Code Cleanliness** + - Is there any debug code left in? + - Are there any TODO comments that should be resolved? + - Are there any `// REVIEW:` comments that weren't addressed? + - Is the code properly formatted? + +4. **Documentation** + - Are inline comments clear where needed? + - Is the review document comprehensive? + - Are any new APIs documented? + +5. **PR Readiness** + - Is the branch up to date with main? + - Are commits atomic and well-described? + - Is the change diff reasonable in size? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... + +PR_SUMMARY: | + ## Summary + [2-3 sentences describing what this PR does] + + ## Key Changes + - [Change 1] + - [Change 2] + + ## Test Plan + - [How to test] +``` + +**Verdict meanings:** +- `APPROVE`: Ready to create PR +- `REQUEST_CHANGES`: Issues to fix before PR creation +- `COMMENT`: Minor items, can create PR but note feedback + +## Notes + +- This is the builder's final self-review before hand-off +- The PR_SUMMARY in your output can be used as the PR description +- Focus on "is this ready for someone else to review" not "is this perfect" +- Any issues found here are cheaper to fix than during integration review diff --git a/codev/protocols/tick/consult-types/spec-review.md b/codev/protocols/tick/consult-types/spec-review.md new file mode 100644 index 0000000..7c9c157 --- /dev/null +++ b/codev/protocols/tick/consult-types/spec-review.md @@ -0,0 +1,55 @@ +# Specification Review Prompt + +## Context +You are reviewing a feature specification during the Specify phase. Your role is to ensure the spec is complete, correct, and feasible before it moves to human approval. + +## Focus Areas + +1. **Completeness** + - Are all requirements clearly stated? + - Are success criteria defined? + - Are edge cases considered? + - Is scope well-bounded (not too broad or vague)? + +2. **Correctness** + - Do requirements make sense technically? + - Are there contradictions? + - Is the problem statement accurate? + +3. **Feasibility** + - Can this be implemented with available tools/constraints? + - Are there obvious technical blockers? + - Is the scope realistic for a single spec? + +4. **Clarity** + - Would a builder understand what to build? + - Are acceptance criteria testable? + - Is terminology consistent? + +## Verdict Format + +After your review, provide your verdict in exactly this format: + +``` +--- +VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT] +SUMMARY: [One-line summary of your assessment] +CONFIDENCE: [HIGH | MEDIUM | LOW] +--- +KEY_ISSUES: +- [Issue 1 or "None"] +- [Issue 2] +... +``` + +**Verdict meanings:** +- `APPROVE`: Spec is ready for human review +- `REQUEST_CHANGES`: Significant issues must be fixed before proceeding +- `COMMENT`: Minor suggestions, can proceed but consider feedback + +## Notes + +- You are NOT reviewing code - you are reviewing the specification document +- Focus on WHAT is being built, not HOW it will be implemented (that's for plan review) +- Be constructive - identify issues AND suggest solutions +- If the spec references other specs, note if context seems missing diff --git a/codev/protocols/tick/protocol.json b/codev/protocols/tick/protocol.json new file mode 100644 index 0000000..a9f1f79 --- /dev/null +++ b/codev/protocols/tick/protocol.json @@ -0,0 +1,151 @@ +{ + "$schema": "../../protocol-schema.json", + "name": "tick", + "version": "1.1.0", + "description": "Amendment workflow for existing SPIR specifications", + "input": { + "type": "spec", + "required": false + }, + "phases": [ + { + "id": "identify", + "name": "Identify Target", + "description": "Find the existing spec to amend", + "type": "once", + "steps": [ + "analyze_requirements", + "find_target_spec", + "verify_spec_integrated", + "determine_tick_number" + ], + "transition": { + "on_complete": "amend_spec" + } + }, + { + "id": "amend_spec", + "name": "Amend Specification", + "description": "Update the existing specification", + "type": "once", + "steps": [ + "analyze_changes_needed", + "update_spec_sections", + "add_amendment_entry", + "commit_spec_changes" + ], + "transition": { + "on_complete": "amend_plan" + } + }, + { + "id": "amend_plan", + "name": "Amend Plan", + "description": "Update the existing plan", + "type": "once", + "steps": [ + "update_plan_phases", + "add_amendment_history", + "commit_plan_changes" + ], + "transition": { + "on_complete": "implement" + } + }, + { + "id": "implement", + "name": "Implement", + "description": "Implement the amendment", + "type": "once", + "steps": [ + "implement_changes", + "self_review", + "commit" + ], + "checks": { + "build": { + "command": "npm run build", + "on_fail": "retry", + "max_retries": 2 + } + }, + "transition": { + "on_complete": "defend" + } + }, + { + "id": "defend", + "name": "Defend", + "description": "Test the amendment", + "type": "once", + "steps": [ + "write_tests", + "run_tests", + "fix_failures" + ], + "checks": { + "tests": { + "command": "npm test", + "on_fail": "implement", + "max_retries": 1 + } + }, + "transition": { + "on_complete": "evaluate" + } + }, + { + "id": "evaluate", + "name": "Evaluate", + "description": "Verify amendment meets requirements", + "type": "once", + "steps": [ + "verify_requirements", + "check_regressions" + ], + "transition": { + "on_complete": "review" + } + }, + { + "id": "review", + "name": "Review", + "description": "Create review document and PR", + "type": "once", + "steps": [ + "create_tick_review", + "create_pr" + ], + "consultation": { + "on": "review", + "models": ["gemini", "codex"], + "type": "impl", + "parallel": true, + "max_rounds": 1 + }, + "gate": "pr" + } + ], + "signals": { + "PHASE_COMPLETE": { + "description": "Signal current phase is complete", + "transitions_to": "next_phase" + }, + "BLOCKED": { + "description": "Signal implementation is blocked", + "requires": "reason" + } + }, + "defaults": { + "mode": "strict", + "consultation": { + "enabled": true, + "models": ["gemini", "codex"], + "parallel": true + }, + "checks": { + "build": "npm run build", + "test": "npm test" + } + } +} diff --git a/codev/protocols/tick/protocol.md b/codev/protocols/tick/protocol.md new file mode 100644 index 0000000..5545223 --- /dev/null +++ b/codev/protocols/tick/protocol.md @@ -0,0 +1,277 @@ +# TICK Protocol +**T**ask **I**dentification, **C**oding, **K**ickout + +## Overview + +TICK is an **amendment workflow** for existing SPIR specifications. Rather than creating new standalone specs, TICK modifies existing spec and plan documents in-place, tracking changes in an "Amendments" section. + +**Core Principle**: TICK is for *refining* existing specs. SPIR is for *creating* new specs. + +**Key Insight**: TICKs are not small SPIRs - they're amendments to existing SPIRs. This eliminates the "TICK vs SPIR" decision problem and keeps related work together. + +## When to Use TICK + +### Use TICK when: +- Making **amendments to an existing SPIR spec** that is already `integrated` +- Small scope (< 300 lines of new/changed code) +- Requirements are clear and well-defined +- No fundamental architecture changes +- Examples: + - Adding a feature to an existing system (e.g., "add password reset to user auth") + - Bug fixes that extend existing functionality + - Configuration changes with logic + - Utility function additions to existing modules + - Refactoring within an existing feature + +### Use SPIR instead when: +- Creating a **new feature from scratch** (no existing spec to amend) +- Major architecture changes (scope too large for amendment) +- Unclear requirements needing exploration +- > 300 lines of code +- Multiple stakeholders need alignment + +### Cannot Use TICK when: +- No relevant SPIR spec exists (create a new SPIR spec instead) +- Target spec is not yet `integrated` (complete the SPIR cycle first) + +## Amendment Workflow + +### Phase 1: Identify Target Spec + +**Input**: User describes the amendment needed + +**Agent Actions**: +1. Analyze the amendment requirements +2. Search for the relevant existing spec to amend +3. Verify the spec exists and is `integrated` +4. Load current spec and plan documents +5. Determine next TICK number (count existing TICK entries + 1) + +**Example**: +``` +User: "Use TICK to add password reset to the auth system" +Agent finds: specs/2-user-authentication.md (status: integrated) +Agent determines: Next TICK is TICK-001 (first amendment) +``` + +### Phase 2: Specification Amendment (Autonomous) + +**Agent Actions**: +1. Analyze what needs to change in the spec +2. Update relevant sections of `specs/NNN-name.md`: + - Problem Statement (if scope expands) + - Success Criteria (if new criteria added) + - Solution Approaches (if design changes) + - Any other section that needs updating +3. Add entry to "Amendments" section at bottom: + ```markdown + ### TICK-001: [Title] (YYYY-MM-DD) + + **Summary**: [One-line description] + + **Problem Addressed**: + [Why this amendment was needed] + + **Spec Changes**: + - [Section]: [What changed] + + **Plan Changes**: + - [Phase/steps]: [What was added/modified] + + **Review**: See `reviews/NNN-name-tick-001.md` + ``` +4. **COMMIT**: `[TICK NNN-NNN] Spec: [description]` + +### Phase 3: Planning Amendment (Autonomous) + +**Agent Actions**: +1. Update `plans/NNN-name.md` with new implementation steps +2. Add/modify phases as needed +3. Add entry to "Amendment History" section at bottom: + ```markdown + ### TICK-001: [Title] (YYYY-MM-DD) + + **Changes**: + - [Phase added]: [Description] + - [Implementation steps]: [What was updated] + + **Review**: See `reviews/NNN-name-tick-001.md` + ``` +4. **COMMIT**: `[TICK NNN-NNN] Plan: [description]` + +### Phase 4: Implementation (Autonomous) + +**Agent Actions**: +1. Execute implementation steps from the plan +2. Write code following fail-fast principles +3. Test functionality +4. **COMMIT**: `[TICK NNN-NNN] Impl: [description]` + +### Phase 5: Review (User Checkpoint) + +**Agent Actions**: +1. Create review document: `reviews/NNN-name-tick-NNN.md` + - What was amended and why + - Changes made to spec and plan + - Implementation challenges + - Lessons learned +2. **Multi-Agent Consultation** (MANDATORY): + - Consult GPT-5 AND Gemini Pro + - Focus: Code quality, missed issues, improvements + - Update review with consultation feedback +3. **Update Architecture Documentation** (if applicable) +4. **COMMIT**: `[TICK NNN-NNN] Review: [description]` +5. **PRESENT TO USER**: Show summary with consultation insights + +**User Actions**: +- Review completed work +- Provide feedback +- Request changes OR approve + +**If Changes Requested**: +- Agent makes changes +- Commits: `[TICK NNN-NNN] Fixes: [description]` +- Updates review document +- Repeats until user approval + +## File Naming Convention + +TICK amendments modify existing files and create new review files: + +| File Type | Pattern | Example | +|-----------|---------|---------| +| Spec (modified) | `specs/NNN-name.md` | `specs/2-user-authentication.md` | +| Plan (modified) | `plans/NNN-name.md` | `plans/2-user-authentication.md` | +| Review (new) | `reviews/NNN-name-tick-NNN.md` | `reviews/2-user-authentication-tick-001.md` | + +**Note**: Spec and plan files are modified in-place. Only the review file is new. + +## Git Commit Strategy + +**TICK commits reference the parent spec and TICK number**: + +``` +[TICK 2-001] Spec: Add password reset feature +[TICK 2-001] Plan: Add password reset implementation +[TICK 2-001] Impl: Add password reset feature +[TICK 2-001] Review: Password reset implementation +[TICK 2-001] Fixes: Address review feedback +``` + +The format `[TICK -]` identifies: +- ``: Parent spec number (e.g., 2) +- ``: TICK amendment number (e.g., 001, 002, 003) + +## Key Differences from SPIR + +| Aspect | SPIR | TICK | +|--------|--------|------| +| Purpose | Create new features | Amend existing features | +| File creation | Creates new spec/plan/review | Modifies spec/plan, creates review | +| Sequential numbering | Gets new number (1, 2) | Uses parent's number (2-001) | +| Scope | Any size | < 300 lines typically | +| Prerequisites | None | Existing integrated spec required | +| User checkpoints | Multiple (spec, plan, phases) | Two (start, end) | +| Multi-agent consultation | Throughout | End only (review) | + +## Protocol Selection Guide + +``` +Is there an existing spec to amend? +├── NO → Use SPIR (create new spec) +└── YES → Is it integrated? + ├── NO → Complete SPIR cycle first + └── YES → Is the change small (<300 LOC)? + ├── YES → Use TICK (amend existing spec) + └── NO → Use SPIR (scope too large) +``` + +**Mental Model**: +- SPIR = Create new feature from scratch +- TICK = Refine/extend existing feature + +## Example TICK Workflow + +**User**: "Add password reset to the user authentication system" + +**Agent**: +1. **Identify**: Finds `specs/2-user-authentication.md` (integrated) +2. **Amend Spec** (30 seconds): + - Updates Success Criteria with password reset requirements + - Adds TICK-001 entry to Amendments section + - Commit: `[TICK 2-001] Spec: Add password reset feature` +3. **Amend Plan** (30 seconds): + - Adds Phase 4: Password Reset Email Service + - Adds TICK-001 entry to Amendment History + - Commit: `[TICK 2-001] Plan: Add password reset implementation` +4. **Implement** (2 minutes): + - Creates password reset endpoint + - Implements email service + - Tests functionality + - Commit: `[TICK 2-001] Impl: Add password reset feature` +5. **Review** (1 minute): + - Creates `reviews/2-user-authentication-tick-001.md` + - Runs 3-way consultation (Gemini, Codex, Claude) + - Commit: `[TICK 2-001] Review: Password reset implementation` + - Shows user the completed work + +**Total Time**: ~4 minutes for simple amendment + +## Multiple TICKs per Spec + +A single spec can have multiple TICK amendments over its lifetime: + +```markdown +## Amendments + +### TICK-003: Add MFA support (2025-03-15) +... + +### TICK-002: Add session timeout (2025-02-01) +... + +### TICK-001: Add password reset (2025-01-15) +... +``` + +TICKs are listed in reverse chronological order (newest first). Each TICK builds on the previous state of the spec. + +## Migration from Standalone TICK + +Existing standalone TICK projects (created before this protocol change) are grandfathered in. No migration required. + +**Optional Migration** (if desired): +1. Identify the "parent spec" the TICK logically extends +2. Move TICK content into an amendment entry in the parent spec +3. Archive the standalone files with a note: "Migrated to spec NNN as TICK-NNN" +4. Update the GitHub Issue to reflect the change + +## Benefits + +1. **Single source of truth**: Spec file shows complete feature evolution +2. **Clear history**: Amendments section documents all changes chronologically +3. **Reduced fragmentation**: Related work stays together +4. **Simpler mental model**: "New vs amendment" is clearer than "SPIR vs TICK" +5. **Preserved context**: Looking at a spec shows all refinements + +## Limitations + +1. **Requires existing spec**: Cannot use TICK for greenfield work +2. **Spec can grow large**: Many TICKs add content (consider: >5 TICKs suggests need for new spec) +3. **Merge conflicts**: Multiple TICKs on same spec may conflict +4. **No course correction**: Can't adjust mid-implementation + +## Best Practices + +1. **Verify spec is integrated**: Never TICK a spec that isn't complete +2. **Keep TICKs small**: If scope grows, consider new SPIR spec +3. **Clear summaries**: Amendment entries should be self-explanatory +4. **Test before review**: Always test functionality before presenting +5. **Honest documentation**: Document all deviations in review + +## Templates + +TICK uses the standard SPIR templates with amendments sections: +- Spec template: `codev/protocols/spir/templates/spec.md` (includes Amendments section) +- Plan template: `codev/protocols/spir/templates/plan.md` (includes Amendment History section) +- Review template: `codev/protocols/tick/templates/review.md` (TICK-specific) diff --git a/codev/protocols/tick/templates/plan.md b/codev/protocols/tick/templates/plan.md new file mode 100644 index 0000000..01b016e --- /dev/null +++ b/codev/protocols/tick/templates/plan.md @@ -0,0 +1,67 @@ +# TICK Plan: [Title] + +## Metadata +- **ID**: ####-[short-name] +- **Protocol**: TICK +- **Specification**: [Link to spec file] +- **Created**: [YYYY-MM-DD] +- **Status**: autonomous + +## Implementation Approach +[Brief description of chosen approach from specification] + +## Implementation Steps + +### Step 1: [Action] +**Files**: [list files to create/modify] +**Changes**: [what to do] + +### Step 2: [Action] +**Files**: [list files to create/modify] +**Changes**: [what to do] + +### Step 3: [Action] +**Files**: [list files to create/modify] +**Changes**: [what to do] + +[Add more steps as needed - keep sequential] + +## Files to Create/Modify + +### New Files +- `path/to/file1.ts` - [purpose] +- `path/to/file2.ts` - [purpose] + +### Modified Files +- `path/to/existing1.ts` - [what changes] +- `path/to/existing2.ts` - [what changes] + +## Testing Strategy + +### Manual Testing +1. [Test scenario 1] +2. [Test scenario 2] +3. [Test scenario 3] + +### Automated Tests (if applicable) +- [Test file 1: what to test] +- [Test file 2: what to test] + +## Success Criteria +- [ ] All steps completed +- [ ] Manual tests pass +- [ ] No breaking changes +- [ ] Code committed + +## Risks +| Risk | If Occurs | +|------|-----------| +| [Risk 1] | [Fallback plan] | +| [Risk 2] | [Fallback plan] | + +## Dependencies +- [Dependency 1] +- [Dependency 2] + +## Notes +[Any implementation notes or considerations] diff --git a/codev/protocols/tick/templates/review.md b/codev/protocols/tick/templates/review.md new file mode 100644 index 0000000..1158f7b --- /dev/null +++ b/codev/protocols/tick/templates/review.md @@ -0,0 +1,89 @@ +# TICK Review: [Title] + +## Metadata +- **ID**: ####-[short-name] +- **Protocol**: TICK +- **Date**: [YYYY-MM-DD] +- **Specification**: [Link to spec file] +- **Plan**: [Link to plan file] +- **Status**: [completed/needs-fixes] + +## Implementation Summary +[Brief description of what was implemented] + +## Success Criteria Status +- [ ] [Criterion 1 from spec] +- [ ] [Criterion 2 from spec] +- [ ] [Criterion 3 from spec] +- [ ] Tests passed +- [ ] No breaking changes + +## Files Changed + +### Created +- `path/to/file1.ts` - [purpose] +- `path/to/file2.ts` - [purpose] + +### Modified +- `path/to/existing1.ts` - [changes made] +- `path/to/existing2.ts` - [changes made] + +## Deviations from Plan +[None if plan was followed exactly, otherwise list what changed and why] + +## Testing Results + +### Manual Tests +1. [Scenario 1] - ✅/❌ +2. [Scenario 2] - ✅/❌ +3. [Scenario 3] - ✅/❌ + +### Automated Tests (if applicable) +- [Test result summary] + +## Challenges Encountered +1. [Challenge 1] + - **Solution**: [How resolved] +2. [Challenge 2] + - **Solution**: [How resolved] + +## Lessons Learned + +### What Went Well +- [Success point 1] +- [Success point 2] + +### What Could Improve +- [Improvement area 1] +- [Improvement area 2] + +## Consultation Feedback + +[For each phase that had consultation, summarize every reviewer's concerns and how the builder responded. Use **Addressed** (fixed), **Rebutted** (disagreed with reasoning), or **N/A** (out of scope/moot) for each concern. If all reviewers approved with no concerns: "No concerns raised — all consultations approved."] + +### [Phase] Phase (Round N) + +#### Gemini +- **Concern**: [Summary of concern] + - **Addressed**: [What was changed] + +#### Codex +- **Concern**: [Summary of concern] + - **Rebutted**: [Why current approach is correct] + +#### Claude +- No concerns raised (APPROVE) + +## TICK Protocol Feedback +- **Autonomous execution**: [Worked well / Issues encountered] +- **Single-phase approach**: [Appropriate / Should have used SPIR] +- **Speed vs quality trade-off**: [Balanced / Too fast / Too slow] +- **End-only consultation**: [Caught issues / Missed opportunities] + +## Follow-Up Actions +- [ ] [Any remaining work] +- [ ] [Technical debt created] +- [ ] [Future enhancements] + +## Conclusion +[Brief summary of outcome and whether TICK was appropriate for this task] diff --git a/codev/protocols/tick/templates/spec.md b/codev/protocols/tick/templates/spec.md new file mode 100644 index 0000000..8282951 --- /dev/null +++ b/codev/protocols/tick/templates/spec.md @@ -0,0 +1,61 @@ +# TICK Specification: [Title] + +## Metadata +- **ID**: ####-[short-name] +- **Protocol**: TICK +- **Created**: [YYYY-MM-DD] +- **Status**: autonomous + +## Task Description +[What needs to be built? Be specific and concise.] + +## Scope + +### In Scope +- [Feature/change 1] +- [Feature/change 2] +- [Feature/change 3] + +### Out of Scope +- [What we're NOT doing] +- [Future considerations] + +## Success Criteria +- [ ] [Specific, testable criterion 1] +- [ ] [Specific, testable criterion 2] +- [ ] [Specific, testable criterion 3] +- [ ] Tests pass +- [ ] No breaking changes + +## Constraints +- [Technical limitation 1] +- [Technical limitation 2] +- [Time/scope constraints] + +## Assumptions +- [Assumption 1] +- [Assumption 2] +- [Dependencies] + +## Implementation Approach +[Brief description of how this will be implemented - single approach only] + +### Key Changes +- [File/component 1: what will change] +- [File/component 2: what will change] +- [File/component 3: what will change] + +## Risks +| Risk | Mitigation | +|------|------------| +| [Risk 1] | [How to handle] | +| [Risk 2] | [How to handle] | + +## Testing Approach +### Test Scenarios +1. [Happy path scenario] +2. [Edge case scenario] +3. [Error scenario] + +## Notes +[Any additional context] diff --git a/codev/resources/commands/agent-farm.md b/codev/resources/commands/agent-farm.md new file mode 100644 index 0000000..bf143be --- /dev/null +++ b/codev/resources/commands/agent-farm.md @@ -0,0 +1,575 @@ +# af - Agent Farm CLI + +The `af` (agent-farm) command manages multi-agent orchestration for software development. It spawns and manages builders in isolated git worktrees. + +## Synopsis + +``` +af [options] +``` + +## Global Options + +``` +--architect-cmd Override architect command +--builder-cmd Override builder command +--shell-cmd Override shell command +``` + +## Commands + +### af workspace + +Workspace commands - start/stop the workspace for this project. + +> **Deprecation note:** `af dash` is a deprecated alias for `af workspace`. It still works but prints a deprecation warning. + +#### af workspace start + +Start the workspace. + +```bash +af workspace start [options] +``` + +**Options:** +- `-c, --cmd ` - Command to run in architect terminal +- `-p, --port ` - Port for architect terminal +- `--no-role` - Skip loading architect role prompt +- `--no-browser` - Skip opening browser after start +- `-r, --remote ` - Start Agent Farm on remote machine (see below) +- `--allow-insecure-remote` - Bind to 0.0.0.0 for remote access (deprecated) + +**Description:** + +Starts the workspace with: +- Architect terminal (Claude session with architect role) +- Web-based UI for monitoring builders +- Terminal session management (shellper processes) + +The workspace overview is accessible via browser at `http://localhost:`. + +**Examples:** + +```bash +# Start with defaults +af workspace start + +# Start with custom port +af workspace start -p 4300 + +# Start with specific command +af workspace start -c "claude --model opus" + +# Start on remote machine +af workspace start --remote user@host +``` + +#### Remote Access + +Start Agent Farm on a remote machine and access it from your local workstation with a single command: + +```bash +# On your local machine - one command does everything: +af workspace start --remote user@remote-host + +# Or with explicit project path: +af workspace start --remote user@remote-host:/path/to/project + +# With custom port: +af workspace start --remote user@remote-host --port 4300 +``` + +This single command: +1. Checks passwordless SSH is configured +2. Verifies CLI versions match between local and remote +3. SSHs into the remote machine +4. Starts Agent Farm there with matching port +5. Sets up SSH tunnel back to your local machine +6. Opens the workspace overview in your browser + +The workspace and all terminals work identically to local development. Press Ctrl+C to disconnect. + +**Port Selection:** + +The port is determined by the global port registry (`af ports list`). Each project gets a consistent 100-port block (e.g., 4200-4299, 4600-4699). The same port is used on both local and remote ends for the SSH tunnel. + +```bash +# Check your project's port allocation +af ports list +``` + +**Prerequisites:** +- SSH server must be running on the remote machine +- Agent Farm (`af`) must be installed on the remote machine +- **Passwordless SSH required** - set up with `ssh-copy-id user@host` +- Same version of codev on both machines (warnings shown if mismatched) + +**Troubleshooting:** + +If the remote can't find `claude` or other commands, ensure they're in your PATH for non-interactive shells. Add to `~/.profile` on the remote: +```bash +export PATH="$HOME/.local/bin:$PATH" +``` + +**Limitation**: File annotation tabs (`af open`) use separate ports and won't work through the tunnel. Use terminals for file viewing, or forward additional ports manually. + +**Legacy mode** (deprecated): + +```bash +# DEPRECATED: Exposes workspace without authentication +af workspace start --allow-insecure-remote +``` + +The `--allow-insecure-remote` flag binds to `0.0.0.0` with no authentication. Use `--remote` instead for secure access via SSH. + +#### af workspace stop + +Stop all agent farm processes for this project. + +```bash +af workspace stop +``` + +**Description:** + +Stops all running agent-farm processes including: +- Terminal sessions (shellper processes) +- Workspace servers + +Does NOT clean up worktrees - use `af cleanup` for that. + +--- + +### af spawn + +Spawn a new builder. + +```bash +af spawn [issue-number] --protocol [options] +``` + +**Arguments:** +- `issue-number` - Issue number to build (positional, e.g., `42`) + +**Required:** +- `--protocol ` - Protocol to use: spir, bugfix, tick, maintain, experiment. **REQUIRED** for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip this flag. + +**Options:** +- `--task ` - Spawn builder with a task description (no `--protocol` needed) +- `--shell` - Spawn a bare Claude session (no `--protocol` needed) +- `--worktree` - Spawn worktree session (no `--protocol` needed) +- `--files ` - Context files (comma-separated) +- `--no-role` - Skip loading role prompt + +**Preconditions:** + +The spawn command requires a **clean git worktree**. Before spawning: + +1. Run `git status` to check for uncommitted changes +2. Commit any pending changes — builders branch from HEAD, so uncommitted specs/plans are invisible to the builder +3. The command will refuse to spawn if the worktree is dirty (override with `--force`, but the builder won't see your uncommitted files) + +**Description:** + +Creates a new builder in an isolated git worktree. The builder gets: +- Its own branch (`builder/-`) +- A dedicated terminal in the workspace overview +- The builder role prompt loaded automatically + +**Examples:** + +```bash +# Spawn builder for issue #42 — --protocol is REQUIRED +af spawn 42 --protocol spir + +# Spawn builder for a bugfix +af spawn 42 --protocol bugfix + +# Spawn with task description (no --protocol needed) +af spawn --task "Fix login bug in auth module" + +# Spawn bare Claude session (no --protocol needed) +af spawn --shell + +# Spawn with context files +af spawn 42 --protocol spir --files "src/auth.ts,tests/auth.test.ts" +``` + +**Common Errors:** + +| Error | Cause | Fix | +|-------|-------|-----| +| "Missing required flag: --protocol" | Forgot `--protocol` | Add `--protocol spir` (or bugfix, tick, etc.) | +| "Dirty worktree" | Uncommitted changes | Run `git status`, commit changes, retry | +| "Builder already exists" | Worktree collision | Use `--resume` to resume, or `af cleanup` first | + +--- + +### af status + +Show status of all agents. + +```bash +af status +``` + +**Description:** + +Displays the current state of all builders and the architect: + +``` +┌────────┬──────────────┬─────────────┬─────────┐ +│ ID │ Name │ Status │ Branch │ +├────────┼──────────────┼─────────────┼─────────┤ +│ arch │ Architect │ running │ main │ +│ 42 │ auth-feature │ implementing│ builder/42-auth │ +│ 43 │ api-refactor │ pr │ builder/43-api │ +└────────┴──────────────┴─────────────┴─────────┘ +``` + +Status values: +- `spawning` - Worktree created, builder starting +- `implementing` - Actively working +- `blocked` - Stuck, needs architect help +- `pr` - Implementation complete +- `complete` - Merged, can be cleaned up + +--- + +### af cleanup + +Clean up a builder worktree and branch. + +```bash +af cleanup -p [options] +``` + +**Options:** +- `-p, --project ` - Builder ID to clean up (required) +- `-f, --force` - Force cleanup even if branch not merged + +**Description:** + +Removes a builder's worktree and associated resources. By default, refuses to delete worktrees with uncommitted changes or unmerged branches. + +**Examples:** + +```bash +# Clean up completed builder +af cleanup -p 42 + +# Force cleanup (may lose work) +af cleanup -p 42 --force +``` + +--- + +### af send + +Send instructions to a running builder. + +```bash +af send [builder] [message] [options] +``` + +**Arguments:** +- `builder` - Builder ID (e.g., `42`) +- `message` - Message to send + +**Options:** +- `--all` - Send to all builders +- `--file ` - Include file content in message +- `--interrupt` - Send Ctrl+C first +- `--raw` - Skip structured message formatting +- `--no-enter` - Do not send Enter after message + +**Description:** + +Sends text to a builder's terminal. Useful for: +- Providing guidance when builder is blocked +- Interrupting long-running processes +- Sending instructions or context + +**Examples:** + +```bash +# Send message to builder +af send 42 "Focus on the auth module first" + +# Interrupt and send new instructions +af send 42 --interrupt "Stop that. Try a different approach." + +# Send to all builders +af send --all "Time to wrap up, create PRs" + +# Include file content +af send 42 --file src/api.ts "Review this implementation" +``` + +--- + +### af open + +Open file annotation viewer. + +```bash +af open +``` + +**Arguments:** +- `file` - Path to file to open + +**Description:** + +Opens a web-based viewer for annotating files with review comments. Comments use the `// REVIEW:` format and are stored directly in the source file. + +**Example:** + +```bash +af open src/auth/login.ts +``` + +--- + +### af shell + +Spawn a utility shell terminal. + +```bash +af shell [options] +``` + +**Options:** +- `-n, --name ` - Name for the shell terminal + +**Description:** + +Opens a general-purpose shell terminal in the workspace overview. Useful for: +- Running tests +- Git operations +- Manual debugging + +**Examples:** + +```bash +# Open utility shell +af shell + +# Open with custom name +af shell -n "test-runner" +``` + +--- + +### af rename + +Rename a builder or utility terminal. + +```bash +af rename +``` + +**Arguments:** +- `id` - Builder or terminal ID +- `name` - New name + +**Example:** + +```bash +af rename 42 "auth-rework" +``` + +--- + +### af ports + +Manage global port registry. + +#### af ports list + +List all port allocations. + +```bash +af ports list +``` + +Shows port blocks allocated to different projects: +``` +Port Allocations +4200-4299: /Users/me/project-a +4300-4399: /Users/me/project-b +``` + +#### af ports cleanup + +Remove stale port allocations. + +```bash +af ports cleanup +``` + +Removes entries for projects that no longer exist. + +--- + +### af tower + +Manage the cross-project tower dashboard. Tower shows all agent-farm instances across projects and provides cloud connectivity via codevos.ai. + +#### af tower start + +Start the tower dashboard. + +```bash +af tower start [options] +``` + +**Options:** +- `-p, --port ` - Port to run on (default: 4100) + +#### af tower stop + +Stop the tower dashboard. + +```bash +af tower stop [options] +``` + +**Options:** +- `-p, --port ` - Port to stop (default: 4100) + +#### af tower register + +Register this tower with codevos.ai for remote access. + +```bash +af tower register [options] +``` + +**Options:** +- `--reauth` - Re-authenticate without changing tower name +- `-p, --port ` - Tower port to signal after registration (default: 4100) + +#### af tower deregister + +Remove this tower's registration from codevos.ai. + +```bash +af tower deregister [options] +``` + +**Options:** +- `-p, --port ` - Tower port to signal after deregistration (default: 4100) + +#### af tower status + +Show tower status including cloud connection info. + +```bash +af tower status [options] +``` + +**Options:** +- `-p, --port ` - Tower port (default: 4100) + +**Environment Variables:** +- `CODEVOS_URL` - Override the codevos.ai server URL (default: `https://codevos.ai`). Useful for local development or staging. + +--- + +### af db + +Database debugging and maintenance commands. + +#### af db dump + +Export all tables to JSON. + +```bash +af db dump [options] +``` + +**Options:** +- `--global` - Dump global.db instead of project db + +#### af db query + +Run a SELECT query. + +```bash +af db query [options] +``` + +**Options:** +- `--global` - Query global.db + +**Example:** + +```bash +af db query "SELECT * FROM builders WHERE status = 'implementing'" +``` + +#### af db reset + +Delete database and start fresh. + +```bash +af db reset [options] +``` + +**Options:** +- `--global` - Reset global.db +- `--force` - Skip confirmation + +#### af db stats + +Show database statistics. + +```bash +af db stats [options] +``` + +**Options:** +- `--global` - Show stats for global.db + +--- + +## Configuration + +Customize commands via `af-config.json` at the project root: + +```json +{ + "shell": { + "architect": "claude --model opus", + "builder": "claude --model sonnet", + "shell": "bash" + } +} +``` + +Or override via CLI flags: + +```bash +af workspace start --architect-cmd "claude --model opus" +af spawn 42 --protocol spir --builder-cmd "claude --model haiku" +``` + +--- + +## Files + +| File | Description | +|------|-------------| +| `.agent-farm/state.db` | Project runtime state (SQLite) | +| `~/.agent-farm/global.db` | Global port registry (SQLite) | +| `af-config.json` | Agent Farm configuration (project root) | + +--- + +## See Also + +- [codev](codev.md) - Project management commands +- [consult](consult.md) - AI consultation +- [overview](overview.md) - CLI overview diff --git a/codev/resources/commands/codev.md b/codev/resources/commands/codev.md new file mode 100644 index 0000000..a7e5b5b --- /dev/null +++ b/codev/resources/commands/codev.md @@ -0,0 +1,176 @@ +# codev - Project Management CLI + +The `codev` command manages project setup, maintenance, and framework-level operations. + +## Synopsis + +``` +codev [options] +``` + +## Commands + +### codev init + +Create a new codev project. + +```bash +codev init [project-name] [options] +``` + +**Arguments:** +- `project-name` - Name of the project (optional, prompts if not provided) + +**Options:** +- `-y, --yes` - Use defaults without prompting + +**Description:** + +Creates a minimal codev project structure: +- `codev/specs/` - Specification files +- `codev/plans/` - Implementation plans +- `codev/reviews/` - Review documents +- `CLAUDE.md` / `AGENTS.md` - AI agent instructions +- `.gitignore` - Standard ignores + +Framework files (protocols, roles) are provided by the embedded skeleton at runtime, not copied to the project. + +**Examples:** + +```bash +# Interactive creation +codev init + +# Create with name +codev init my-app + +# Non-interactive with defaults +codev init my-app -y +``` + +--- + +### codev adopt + +Add codev to an existing project. + +```bash +codev adopt [options] +``` + +**Options:** +- `-y, --yes` - Skip conflict prompts + +**Description:** + +Adds codev structure to the current directory. Detects existing files (CLAUDE.md, AGENTS.md) and prompts before overwriting. + +Use this when you want to add codev to a project that already has code. + +**Examples:** + +```bash +# Add to current project +cd existing-project +codev adopt + +# Skip prompts for conflicts +codev adopt -y +``` + +--- + +### codev doctor + +Check system dependencies. + +```bash +codev doctor +``` + +**Description:** + +Verifies that all required dependencies are installed and properly configured: + +**Core Dependencies (required):** +- Node.js (>= 18.0.0) +- git (>= 2.5.0) +- gh (GitHub CLI, authenticated) + +**AI CLI Dependencies (at least one required):** +- Claude (`@anthropic-ai/claude-code`) +- Gemini (`gemini-cli`) +- Codex (`@openai/codex`) + +**Exit Codes:** +- `0` - All OK or warnings only +- `1` - Required dependencies missing + +**Example:** + +```bash +codev doctor +``` + +Output: +``` +Codev Doctor - Checking your environment +============================================ + +Core Dependencies (required for Agent Farm) + + ✓ Node.js 20.10.0 + ✓ git 2.42.0 + ✓ gh authenticated + ✓ @cluesmith/codev 1.0.0 + +AI CLI Dependencies (at least one required) + + ✓ Claude working + ✓ Gemini working + ○ Codex not installed (npm i -g @openai/codex) + +============================================ +ALL OK - Your environment is ready for Codev! +``` + +--- + +### codev update + +Update codev templates and protocols. + +```bash +codev update [options] +``` + +**Options:** +- `-n, --dry-run` - Show changes without applying +- `-f, --force` - Force update, overwrite all files + +**Description:** + +Updates framework files (protocols, roles, agents) from the installed `@cluesmith/codev` package. User data (specs, plans, reviews) is never modified. + +If you've customized a file locally, the update creates a `.codev-new` file with the new version so you can merge changes manually. + +**Examples:** + +```bash +# Preview changes +codev update --dry-run + +# Apply updates +codev update + +# Force overwrite (discard local changes) +codev update --force +``` + +--- + +## See Also + +- [af](agent-farm.md) - Agent Farm commands +- [consult](consult.md) - AI consultation +- [overview](overview.md) - CLI overview diff --git a/codev/resources/commands/consult.md b/codev/resources/commands/consult.md new file mode 100644 index 0000000..135bb67 --- /dev/null +++ b/codev/resources/commands/consult.md @@ -0,0 +1,200 @@ +# consult - AI Consultation CLI + +The `consult` command provides a unified interface for AI consultation with external models (Gemini, Codex, Claude). It operates in three modes: general (ad-hoc prompts), protocol-based (structured reviews), and stats. + +## Synopsis + +``` +consult -m [options] +consult stats [options] +``` + +## Required Option + +``` +-m, --model Model to use (required for all modes except stats) +``` + +## Models + +| Model | Alias | Backend | Notes | +|-------|-------|---------|-------| +| `gemini` | `pro` | gemini-cli | File access via --yolo, fast | +| `codex` | `gpt` | @openai/codex | Read-only sandbox, thorough | +| `claude` | `opus` | Claude Agent SDK | Balanced analysis with tool use | + +## Modes + +### General Mode + +Send an ad-hoc prompt to a model. + +```bash +# Inline prompt +consult -m gemini --prompt "What's the best way to structure auth middleware?" + +# Prompt from file +consult -m codex --prompt-file review-checklist.md +``` + +**Options:** +- `--prompt ` — Inline prompt text +- `--prompt-file ` — Read prompt from a file + +Cannot combine `--prompt` with `--prompt-file` or `--type`. + +### Protocol Mode + +Run structured reviews tied to a development protocol (SPIR, TICK, bugfix, maintain). + +```bash +# Review a spec (auto-detects project context in builder worktrees) +consult -m gemini --protocol spir --type spec + +# Review a plan +consult -m codex --protocol spir --type plan + +# Review implementation +consult -m claude --protocol spir --type impl + +# Review a PR +consult -m gemini --protocol spir --type pr + +# Phase-scoped review (builder context only) +consult -m codex --protocol spir --type phase + +# Integration review +consult -m gemini --type integration +``` + +**Options:** +- `--protocol ` — Protocol: spir, bugfix, tick, maintain +- `-t, --type ` — Review type: spec, plan, impl, pr, phase, integration +- `--issue ` — Issue number (required from architect context) + +**Context resolution:** +- **Builder context** (cwd inside `.builders/`): auto-detects project ID, spec, plan, and PR from porch state +- **Architect context** (cwd outside `.builders/` or `--issue` provided): requires `--issue ` to identify the project + +**Prompt templates:** +Protocol-specific prompts are loaded from `codev/protocols//consult-types/-review.md`. The `integration` type uses the shared `codev/consult-types/integration-review.md`. + +### Stats Mode + +View consultation statistics and history. + +```bash +consult stats +consult stats --days 7 +consult stats --project 42 +consult stats --last 10 +consult stats --json +``` + +**Options:** +- `--days ` — Limit to last N days (default: 30) +- `--project ` — Filter by project ID +- `--last ` — Show last N individual invocations +- `--json` — Output as JSON + +## Porch Integration Options + +These flags are used by porch (the protocol orchestrator) when generating consult commands. They're not typically used directly. + +``` +--output Write output to file +--plan-phase Scope review to a specific plan phase +--context Context file with previous iteration feedback +--project-id Project ID for metrics +``` + +## Parallel Consultation (3-Way Reviews) + +For thorough reviews, run multiple models in parallel: + +```bash +# 3-way spec review +consult -m gemini --protocol spir --type spec & +consult -m codex --protocol spir --type spec & +consult -m claude --protocol spir --type spec & +wait +``` + +## Performance + +| Model | Typical Time | Approach | +|-------|--------------|----------| +| Gemini | ~120-150s | File access via --yolo, pure text output | +| Codex | ~200-250s | Shell command exploration, read-only sandbox | +| Claude | ~60-120s | Agent SDK with Read/Glob/Grep tools | + +## Prerequisites + +Install the model CLIs you plan to use: + +```bash +# Claude Agent SDK +npm install -g @anthropic-ai/claude-code + +# Codex +npm install -g @openai/codex + +# Gemini +# See: https://github.com/google-gemini/gemini-cli +``` + +Configure API keys: +- Claude: `ANTHROPIC_API_KEY` +- Codex: `OPENAI_API_KEY` +- Gemini: `GOOGLE_API_KEY` or `GEMINI_API_KEY` + +## The Consultant Role + +The consultant role (`codev/roles/consultant.md`) defines behavior: +- Provides second perspectives on decisions +- Offers alternatives and considerations +- Works constructively (not adversarial, not a rubber stamp) + +Customize by editing your local `codev/roles/consultant.md`. + +## Query Logging + +All consultations are logged to `.consult/history.log`: + +``` +2026-02-16T10:30:00.000Z model=gemini duration=142.3s query=Review spec... +``` + +## Examples + +```bash +# General: ask a question +consult -m gemini --prompt "How should I structure the caching layer?" + +# General: from file +consult -m codex --prompt-file design-question.md + +# Protocol: spec review (builder context, auto-detected) +consult -m gemini --protocol spir --type spec + +# Protocol: PR review (architect context) +consult -m codex --protocol spir --type pr --issue 42 + +# Protocol: implementation review with bugfix protocol +consult -m claude --protocol bugfix --type impl + +# 3-way parallel review +consult -m gemini --protocol spir --type spec & +consult -m codex --protocol spir --type spec & +consult -m claude --protocol spir --type spec & +wait + +# Stats +consult stats --days 7 --json +``` + +## See Also + +- [codev](codev.md) - Project management commands +- [af](agent-farm.md) - Agent Farm commands +- [overview](overview.md) - CLI overview diff --git a/codev/resources/commands/overview.md b/codev/resources/commands/overview.md new file mode 100644 index 0000000..5e21870 --- /dev/null +++ b/codev/resources/commands/overview.md @@ -0,0 +1,96 @@ +# Codev CLI Command Reference + +Codev provides three CLI tools for AI-assisted software development: + +| Tool | Description | +|------|-------------| +| `codev` | Project setup, maintenance, and framework commands | +| `af` | Agent Farm - multi-agent orchestration for development | +| `consult` | AI consultation with external models (Gemini, Codex, Claude) | + +## Quick Start + +```bash +# Create a new project +codev init my-project + +# Or add codev to an existing project +codev adopt + +# Check your environment +codev doctor + +# Start the workspace +af workspace start + +# Consult an AI model about a spec +consult -m gemini --protocol spir --type spec +``` + +## Installation + +```bash +npm install -g @cluesmith/codev +``` + +This installs all three commands globally: `codev`, `af`, and `consult`. + +## Command Summaries + +### codev - Project Management + +| Command | Description | +|---------|-------------| +| `codev init [name]` | Create a new codev project | +| `codev adopt` | Add codev to an existing project | +| `codev doctor` | Check system dependencies | +| `codev update` | Update codev templates and protocols | +| `codev import ` | AI-assisted protocol import from other projects | + +See [codev.md](codev.md) for full documentation. + +### af - Agent Farm + +| Command | Description | +|---------|-------------| +| `af workspace start` | Start the workspace | +| `af workspace stop` | Stop all agent farm processes | +| `af spawn` | Spawn a new builder | +| `af status` | Show status of all agents | +| `af cleanup` | Clean up a builder worktree | +| `af send` | Send instructions to a builder | +| `af open` | Open file annotation viewer | +| `af shell` | Spawn a utility shell | +| `af tower` | Cross-project dashboard | + +See [agent-farm.md](agent-farm.md) for full documentation. + +### consult - AI Consultation + +| Command | Description | +|---------|-------------| +| `consult -m --prompt "text"` | General consultation | +| `consult -m --protocol spir --type spec` | Protocol-based review | +| `consult stats` | View consultation statistics | + +See [consult.md](consult.md) for full documentation. + +## Global Options + +All codev commands support: + +```bash +--version Show version number +--help Show help for any command +``` + +## Configuration + +Agent Farm is configured via `af-config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`. + +## Related Documentation + +- [SPIR Protocol](../protocols/spir/protocol.md) - Multi-phase development workflow +- [TICK Protocol](../protocols/tick/protocol.md) - Fast amendment workflow +- [Architect Role](../roles/architect.md) - Architect responsibilities +- [Builder Role](../roles/builder.md) - Builder responsibilities diff --git a/codev/resources/workflow-reference.md b/codev/resources/workflow-reference.md new file mode 100644 index 0000000..a3d128e --- /dev/null +++ b/codev/resources/workflow-reference.md @@ -0,0 +1,250 @@ +# Architect-Builder Workflow Reference + +Quick reference for the 7-stage project workflow. For protocol details, see `codev/protocols/spir/protocol.md`. + +## Workflow Overview + +``` + CONCEPTION PLANNING EXECUTION +┌─────────────────────────────────────────────────────────────────────────────────────┐ +│ │ +│ → 1. CONCEIVED │ +│ User describes project concept │ +│ Architect creates GitHub Issue, writes spec │ +│ Architect does 3-way spec review │ +│ ⏸️ HUMAN GATE: Approve spec │ +│ │ +│ → 2. SPECIFIED │ +│ Human approves spec │ +│ Architect writes plan │ +│ Architect does 3-way plan review │ +│ Human reviews and approves plan │ +│ │ +│ → 3. PLANNED │ +│ Architect commits spec + plan to main │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ IMPLEMENTATION │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ → 4. IMPLEMENTING │ +│ Architect spawns builder: af spawn XXXX │ +│ Builder reads spec and plan │ +│ For each phase: Implement → Defend → Evaluate │ +│ Builder commits after each phase │ +│ │ +│ → 5. IMPLEMENTED │ +│ Builder writes review doc │ +│ Builder creates PR, notifies architect │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ HANDOFF / INTEGRATION │ +├─────────────────────────────────────────────────────────────────────────────────────┤ +│ → 6. COMMITTED │ +│ Architect assesses PR risk: gh pr diff --stat N │ +│ Low: Read + merge | Medium: 1-model review | High: 3-way CMAP │ +│ Architect iterates with builder via PR comments │ +│ Architect tells builder to merge │ +│ Builder merges PR (NO --delete-branch flag) │ +│ Architect cleans up builder │ +│ │ +│ ⏸️ HUMAN GATE: Validate in production │ +│ → 7. INTEGRATED │ +│ Human validates and marks as integrated │ +└─────────────────────────────────────────────────────────────────────────────────────┘ +``` + +## Stage Quick Reference + +| Stage | Status | Actor | Key Action | Exit Condition | +|-------|--------|-------|------------|----------------| +| 1 | conceived | Architect | Write spec, 3-way review | Human approves spec | +| 2 | specified | Human + Architect | Write plan, 3-way review | Human approves plan | +| 3 | planned | Architect | Commit spec + plan | Committed to main | +| 4 | implementing | Builder | IDE loop per phase | All phases complete | +| 5 | implemented | Builder | Write review, create PR | PR created | +| 6 | committed | Architect + Builder | Risk-based integration review, merge | PR merged | +| 7 | integrated | Human | Validate production | Human confirms | + +## Human Gates + +There are **two points where only a human can advance the workflow**: + +1. **conceived → specified**: Human must approve the specification +2. **committed → integrated**: Human must validate production deployment + +AI agents must stop and wait for human action at these gates. + +## Common Commands + +### Architect Commands + +```bash +# Start the workspace +af workspace start + +# Spawn a builder for a project +af spawn 44 --protocol spir + +# Check all builder statuses +af status + +# Send message to builder +af send 44 "Check PR comments and address feedback" + +# Open a file for review +af open codev/specs/44-name.md + +# Clean up after merge +af cleanup -p 44 + +# Stop everything +af workspace stop +``` + +### Builder Commands + +```bash +# Check your own status +af status + +# Send message to architect +af send architect "Question about the spec..." + +# Open a file in the annotation viewer +af open src/path/to/file.ts +``` + +### Protocol Import + +```bash +# Import protocol improvements from another project +codev import /path/to/other-project + +# Import from GitHub +codev import github:cluesmith/codev + +# Preview without running Claude +codev import github:owner/repo --dry-run +``` + +### Consultation Commands + +```bash +# Spec review (during Stage 1) +consult -m gemini --protocol spir --type spec +consult -m codex --protocol spir --type spec + +# Plan review (during Stage 2) +consult -m gemini --protocol spir --type plan +consult -m codex --protocol spir --type plan + +# Implementation review (during Stage 4, after each phase) +consult -m gemini --protocol spir --type impl +consult -m codex --protocol spir --type impl + +# PR review (during Stage 5) +consult -m gemini --protocol spir --type pr +consult -m codex --protocol spir --type pr + +# Integration review (during Stage 6 — depth depends on risk) +# Low risk: no consult needed, architect reads and merges +# Medium risk: single-model review +consult -m claude --type integration pr N +# High risk: full 3-way CMAP +consult -m gemini --type integration pr N & +consult -m codex --type integration pr N & +consult -m claude --type integration pr N & +wait + +# Parallel 3-way reviews (run all three concurrently) +consult -m gemini --protocol spir --type spec & +consult -m codex --protocol spir --type spec & +consult -m claude --protocol spir --type spec & +wait +``` + +## Review Types + +| Type | When Used | Focus | +|------|-----------|-------| +| `spec` | Stage 1 | Requirements clarity, completeness, feasibility | +| `plan` | Stage 2 | Implementation approach, phase breakdown, risk assessment | +| `impl` | Stage 4 | Code quality, test coverage, spec adherence | +| `pr` | Stage 5 | Final self-check before PR creation | +| `integration` | Stage 6 | System fit, architectural consistency, side effects (depth varies by risk — see `codev/resources/risk-triage.md`) | + +## Builder Lifecycle + +``` +spawning → implementing → blocked → implementing → pr → complete + ↑______________| +``` + +| Status | Meaning | +|--------|---------| +| `spawning` | Worktree created, builder starting up | +| `implementing` | Actively working on the spec | +| `blocked` | Stuck, needs architect help | +| `pr` | Implementation complete, ready for review | +| `complete` | Merged, worktree can be cleaned up | + +## Git Workflow + +### Branch Naming +``` +builder/XXXX-spec-name +``` + +### Commit Messages +``` +[Spec XXXX][Implement] Phase description +[Spec XXXX][Defend] Add tests for phase +[Spec XXXX][Review] Add lessons learned +``` + +### PR Merge (Builder) +```bash +# CORRECT - preserves branch for worktree +gh pr merge N --merge + +# WRONG - breaks worktree +gh pr merge N --merge --delete-branch +``` + +### Post-Merge Cleanup (Architect) +```bash +git pull # Get merged changes +af cleanup -p XXXX # Clean up builder worktree +``` + +## Troubleshooting + +### Builder Reports Blocked + +1. Check builder terminal for blocker message +2. Review any `// REVIEW(@architect):` comments in code +3. Provide guidance via `af send XXXX "guidance here"` +4. Builder will resume work after receiving help + +### PR Has Conflicts + +1. Architect: `git pull` on main +2. Architect: Resolve conflicts or instruct builder +3. Builder: Rebase or merge main into branch +4. Builder: Force push if needed + +### Builder Worktree Broken + +```bash +# Check worktree status +git worktree list + +# Force cleanup (only if work is committed/pushed) +af cleanup -p XXXX --force +``` + +## Related Documentation + +- Full SPIR protocol: `codev/protocols/spir/protocol.md` +- Builder role: `codev/roles/builder.md` +- Architect role: `codev/roles/architect.md` +- Consultant role: `codev/roles/consultant.md` +- Risk triage guide: `codev/resources/risk-triage.md` diff --git a/codev/reviews/14-tick-001-jj-auto-install.md b/codev/reviews/14-tick-001-jj-auto-install.md new file mode 100644 index 0000000..4dd737d --- /dev/null +++ b/codev/reviews/14-tick-001-jj-auto-install.md @@ -0,0 +1,86 @@ +# Review: TICK 14-001 — JJ Auto-Install CLI Command + +**Date**: 2026-02-27 +**Protocol**: TICK +**Spec**: `codev/specs/14-tick-001-jj-auto-install.md` + +## What Was Amended + +Added `fava-trails install-jj` subcommand to eliminate the adoption cliff between `pip install fava-trails` and a working system. Updated all "jj not found" error messages to reference `fava-trails install-jj` instead of the non-existent (in PyPI packages) `scripts/install-jj.sh`. + +## Changes Made + +### Spec Changes +- Standalone TICK spec at `codev/specs/14-tick-001-jj-auto-install.md` (authored by architect) + +### Plan Changes +- Standalone TICK plan at `codev/plans/14-tick-001-jj-auto-install.md` (authored by architect) + +### Implementation + +**`src/fava_trails/cli.py`**: +- Added imports: `platform`, `tarfile`, `tempfile`, `urllib.error`, `urllib.request` +- Added `JJ_DEFAULT_VERSION = "0.28.0"` and `_JJ_INSTALL_DIR` constant +- Added `cmd_install_jj()` function (~110 LOC): + - Platform check first (Windows → winget instructions, return 1) + - Version-aware skip: checks installed JJ version, exits 0 if matches + - Platform/arch detection for Linux x86_64/aarch64, macOS x86_64/arm64 + - Downloads via `urlopen(timeout=30)` (no new dependencies) + - Safe tarball extraction via `extractfile()` + manual write (avoids path traversal) + - Filesystem error handling with actionable messages + - Post-install PATH check with shell snippet +- Registered `install-jj` subparser with `--version` flag +- Updated `cmd_bootstrap` error message (line ~212) +- Updated `cmd_doctor` fix suggestion (line ~427) + +**`src/fava_trails/vcs/jj_backend.py`**: +- Updated `_find_jj()` error message to reference `fava-trails install-jj` + +**`tests/conftest.py`**: +- Updated skip message to reference `fava-trails install-jj` + +**`tests/test_cli.py`**: +- Added `cmd_install_jj` to imports +- Updated `test_doctor_missing_jj` assertion (`install-jj` not `install-jj.sh`) +- Added 6 new tests: skip-if-version-matches, Windows/winget, unsupported arch, download+install, custom version URL, appears-in-help + +## Implementation Challenges + +**tarfile extraction**: Initial implementation used `tf.extract()` which triggers a Python 3.12+ DeprecationWarning and is a potential path traversal vector. Replaced with `extractfile()` + manual `shutil.copyfileobj()` write — eliminates the entire traversal class of bugs. + +**Test isolation for platform mocking**: Tests patching `sys.platform = "win32"` caused `shutil.which()` to internally call `_winapi.NeedCurrentDirectoryForExePath` which doesn't exist on Linux. Fixed by also patching `shutil.which`. + +**Test isolation for already-installed check**: Tests for unsupported platform/arch were short-circuiting via the "already installed" check (real JJ is installed on CI). Fixed by reordering: platform check now happens *before* the version check, since Windows users shouldn't run the Linux installer path at all. + +**urlopen context manager**: The `urlopen` mock needed a proper context manager interface (`__enter__`/`__exit__`) since the implementation uses it as `with urllib.request.urlopen(...) as r`. + +## Multi-Agent Consultation + +Ran `mcp__pal__codereview` with GPT-5.1 expert analysis. Key findings actioned: + +| Issue | Severity | Action | +|-------|----------|--------| +| `tf.extract()` path traversal / Python 3.12+ deprecation | Critical | Fixed: use `extractfile()` + manual write | +| `jj version` vs `jj --version` inconsistency | High | Fixed: use `--version` everywhere | +| `urlretrieve` has no timeout | High | Fixed: use `urlopen(timeout=30)` | +| Filesystem ops not wrapped in try/except | Medium | Fixed: added `OSError` handler | +| `./jj` member name path handling | Low | Fixed: use `Path(m.name).name` | + +## Lessons Learned + +1. **Test platform mocking carefully**: Patching `sys.platform` without also patching stdlib functions that branch on it (like `shutil.which`) causes internal errors on non-Windows platforms. +2. **Safe tarball extraction pattern**: Always use `extractfile()` + manual write for network-downloaded tarballs. Never use `tf.extract()` without `filter='data'`. +3. **urlopen needs context manager mock**: When mocking `urlopen`, provide a proper `__enter__`/`__exit__` mock since `with urlopen(...) as r` is the canonical pattern. +4. **Order platform check before version check**: For commands with platform-specific behavior, check unsupported platforms first to fail fast with actionable messages. + +## Success Criteria Verification + +- [x] `fava-trails install-jj` subcommand exists and is registered +- [x] Linux x86_64, Linux aarch64, macOS x86_64, macOS arm64 supported +- [x] Windows detection prints winget instructions +- [x] Version-aware skip: exits 0 if installed version matches +- [x] `--version` flag allows pinning a different JJ version +- [x] Zero references to `scripts/install-jj.sh` in Python source/tests +- [x] All error messages point to `fava-trails install-jj` +- [x] 6 new tests added; all 187 tests pass +- [x] No new PyPI dependencies (stdlib only) diff --git a/codev/roles/architect.md b/codev/roles/architect.md new file mode 100644 index 0000000..da87232 --- /dev/null +++ b/codev/roles/architect.md @@ -0,0 +1,298 @@ +# Role: Architect + +The Architect is the **project manager and gatekeeper** who decides what to build, spawns builders, approves gates, and ensures integration quality. + +> **Quick Reference**: See `codev/resources/workflow-reference.md` for stage diagrams and common commands. + +## Key Concept: Spawning Builders + +Builders work autonomously in isolated git worktrees. The Architect: +1. **Decides** what to build +2. **Spawns** builders via `af spawn` +3. **Approves** gates (spec-approval, plan-approval) when in strict mode +4. **Reviews** PRs for integration concerns + +### Two Builder Modes + +| Mode | Command | Use When | +|------|---------|----------| +| **Strict** (default) | `af spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion | +| **Soft** | `af spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance | + +**Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention. + +**Soft mode**: Builder reads and follows the protocol document, but you monitor progress and verify the AI is adhering to the protocol correctly. Use when you want more hands-on oversight. + +### Pre-Spawn Checklist + +**Before every `af spawn`, complete these steps:** + +1. **`git status`** — Ensure worktree is clean (no uncommitted changes) +2. **Commit if needed** — Builders branch from HEAD; uncommitted specs/plans are invisible +3. **`af spawn N --protocol `** — `--protocol` is **REQUIRED** (spir, bugfix, tick, etc.) + +The spawn command will refuse if the worktree is dirty (override with `--force`, but your builder won't see uncommitted files). + +## Key Tools + +### Agent Farm CLI (`af`) + +```bash +af spawn 1 --protocol spir # Strict mode (default) - porch-driven +af spawn 1 --protocol spir -t "feature" # Strict mode with title (no spec yet) +af spawn 1 --resume # Resume existing porch state +af spawn 1 --protocol spir --soft # Soft mode - protocol-guided +af spawn --task "fix the bug" # Ad-hoc task builder (soft mode) +af spawn --worktree # Worktree with no initial prompt +af status # Check all builders +af cleanup -p 0001 # Remove completed builder +af workspace start/stop # Workspace management +af send 0001 "message" # Short message to builder +``` + +> **Note:** `--protocol` is REQUIRED for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip it. + +**Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory. + +### Porch CLI (for strict mode) + +```bash +porch status 0001 # Check project state +porch approve 0001 spec-approval # Approve a gate +porch pending # List pending gates +``` + +### Consult Tool (for integration reviews) + +```bash +# Single-model review (medium risk) +consult -m claude --type integration pr 35 + +# 3-way parallel review (high risk) +consult -m gemini --type integration pr 35 & +consult -m codex --type integration pr 35 & +consult -m claude --type integration pr 35 & +wait +``` + +## Responsibilities + +1. **Decide what to build** - Identify features, prioritize work +2. **Track projects** - Use GitHub Issues as the project registry +3. **Spawn builders** - Choose soft or strict mode based on needs +4. **Approve gates** - (Strict mode) Review specs and plans, approve to continue +5. **Monitor progress** - Track builder status, unblock when stuck +6. **Integration review** - Review PRs for architectural fit +7. **Manage releases** - Group projects into releases + +## Workflow + +### 1. Starting a New Feature + +```bash +# 1. Create a GitHub Issue for the feature +# 2. Ensure worktree is clean: git status → commit if needed +# 3. Spawn the builder (--protocol is REQUIRED) + +# Default: Strict mode (porch-driven with gates) +af spawn 42 --protocol spir + +# With project title (if no spec exists yet) +af spawn 42 --protocol spir -t "user-authentication" + +# Or: Soft mode (builder follows protocol independently) +af spawn 42 --protocol spir --soft + +# For bugfixes +af spawn 42 --protocol bugfix +``` + +### 2. Approving Gates (Strict Mode Only) + +The builder stops at gates requiring approval: + +**spec-approval** - After builder writes the spec +```bash +# Review the spec in the builder's worktree +cat worktrees/spir_0042_user-authentication/codev/specs/0042-user-authentication.md + +# Approve if satisfactory +porch approve 0042 spec-approval +``` + +**plan-approval** - After builder writes the plan +```bash +# Review the plan +cat worktrees/spir_0042_user-authentication/codev/plans/0042-user-authentication.md + +# Approve if satisfactory +porch approve 0042 plan-approval +``` + +### 3. Monitoring Progress + +```bash +af status # Overview of all builders +porch status 0042 # Detailed state for one project (strict mode) +``` + +### 4. Integration Review (Risk-Based Triage) + +When the builder creates a PR, **assess risk first** before deciding review depth. + +> **Full reference**: See `codev/resources/risk-triage.md` for subsystem mappings and examples. + +#### Step 1: Assess Risk + +```bash +gh pr diff --stat # See lines changed and files touched +gh pr view --json files | jq '.files[].path' # See which subsystems +``` + +#### Step 2: Triage + +| Risk | Criteria | Action | +|------|----------|--------| +| **Low** | <100 lines, 1-3 files, isolated (docs, tests, cosmetic, bugfixes) | Read PR, summarize root cause + fix, tell builder to merge | +| **Medium** | 100-500 lines, 4-10 files, touches shared code (features, commands) | Single-model review: `consult -m claude --type integration pr N` | +| **High** | >500 lines, >10 files, core subsystems (porch, Tower, protocols, security) | Full 3-way CMAP (see below) | + +**Precedence: highest factor wins.** If any single factor (lines, files, subsystem, or cross-cutting scope) is high-risk, treat the whole PR as high-risk. + +**Typical mappings:** +- **Low**: Most bugfixes, ASPIR features, documentation, UI tweaks +- **Medium**: SPIR features, new commands, refactors touching 3+ files +- **High**: Protocol changes, porch state machine, Tower architecture, security model + +#### Step 3: Execute Review + +**Low risk** — no external models needed: +```bash +# Read the PR yourself, then approve +gh pr comment 83 --body "## Architect Review + +Low-risk change. [Summary of what changed and why.] + +--- +Architect review" + +af send 0042 "PR approved, please merge" +``` + +**Medium risk** — single-model review: +```bash +consult -m claude --type integration pr 83 + +# Post findings as PR comment +gh pr comment 83 --body "## Architect Integration Review +... +Architect integration review" + +af send 0042 "PR approved, please merge" +``` + +**High risk** — full 3-way CMAP: +```bash +consult -m gemini --type integration pr 83 & +consult -m codex --type integration pr 83 & +consult -m claude --type integration pr 83 & +wait + +# Post findings as PR comment +gh pr comment 83 --body "## Architect Integration Review +... +Architect integration review" + +af send 0042 "PR approved, please merge" +``` + +### 5. Cleanup + +After builder merges and work is integrated: + +```bash +af cleanup -p 0042 +``` + +## Critical Rules + +### NEVER Do These: +1. **DO NOT merge PRs yourself** - Let builders merge their own PRs +2. **DO NOT commit directly to main** - All changes go through builder PRs +3. **DO NOT use `af send` for long messages** - Use GitHub PR comments instead +4. **DO NOT run `af` commands from inside a builder worktree** - All `af` commands must be run from the repository root on `main`. Spawning from a worktree nests builders inside it, breaking everything. +5. **DO NOT `cd` into a builder worktree** - All CLI tools (`af`, `porch`, `consult`, `codev`) are global commands that work from any directory. If a command fails, debug it — don't cd into the worktree. Use absolute paths with the Read tool to inspect builder files (e.g., `Read /path/to/.builders/0042/codev/specs/...`). + +### ALWAYS Do These: +1. **Create GitHub Issues first** - Track projects as issues before spawning +2. **Review artifacts before approving gates** - (Strict mode) Read the spec/plan carefully +3. **Use PR comments for feedback** - Not terminal send-keys +4. **Let builders own their work** - Guide, don't take over +5. **Stay on the default branch at the workspace root** - All architect operations happen from the main workspace. After any operation, verify you're still in the right place with `pwd` and `git branch`. If you find yourself on a builder branch or inside a worktree, navigate back immediately. + +## Project Tracking + +**GitHub Issues are the canonical source of truth for project tracking.** + +```bash +# See what needs work +gh issue list --label "priority:high" + +# View a specific project +gh issue view 42 +``` + +Update status as projects progress: +- `conceived` → `specified` → `planned` → `implementing` → `committed` → `integrated` + +## Handling Blocked Builders + +When a builder reports blocked: + +1. Check their status: `af status` or `porch status ` +2. Read their output in the terminal: `http://localhost:` +3. Provide guidance via short `af send` message +4. Or answer their question directly if they asked one + +## Release Management + +The Architect manages releases - deployable units grouping related projects. + +``` +planning → active → released → archived +``` + +- Only **one release** should be `active` at a time +- Projects should be assigned to a release before `implementing` +- All projects must be `integrated` before release is marked `released` + +## UX Verification (Critical) + +Before approving implementations with UX requirements: + +1. **Read the spec's Goals section** +2. **Manually test** the actual user experience +3. Verify each UX requirement is met + +**Auto-reject if:** +- Spec says "async" but implementation is synchronous +- Spec says "immediate" but user waits 30+ seconds +- Spec has flow diagram that doesn't match reality + +## Quick Reference + +| Task | Command | +|------|---------| +| Start feature (strict, default) | `af spawn --protocol spir` | +| Start feature (soft) | `af spawn --protocol spir --soft` | +| Start bugfix | `af spawn --protocol bugfix` | +| Check all builders | `af status` | +| Check one project | `porch status ` | +| Approve spec | `porch approve spec-approval` | +| Approve plan | `porch approve plan-approval` | +| See pending gates | `porch pending` | +| Assess PR risk | `gh pr diff --stat N` | +| Integration review (medium) | `consult -m claude --type integration pr N` | +| Integration review (high) | 3-way CMAP (see Section 4) | +| Message builder | `af send "short message"` | +| Cleanup builder | `af cleanup -p ` | diff --git a/codev/roles/builder.md b/codev/roles/builder.md new file mode 100644 index 0000000..92daa30 --- /dev/null +++ b/codev/roles/builder.md @@ -0,0 +1,182 @@ +# Role: Builder + +A Builder is an implementation agent that works on a single project in an isolated git worktree. + +## Two Operating Modes + +Builders run in one of two modes, determined by how they were spawned: + +| Mode | Command | Behavior | +|------|---------|----------| +| **Strict** (default) | `af spawn XXXX` | Porch orchestrates - runs autonomously to completion | +| **Soft** | `af spawn XXXX --soft` | AI follows protocol - architect verifies compliance | + +## Strict Mode (Default) + +Spawned with: `af spawn XXXX` + +In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**. + +### The Core Loop + +```bash +# 1. Check your current state +porch status + +# 2. Run the protocol loop +porch run + +# 3. If porch hits a gate, STOP and wait for human approval +# 4. After gate approval, run porch again +# 5. Repeat until project is complete +``` + +Porch handles: +- Spawning Claude to create artifacts (spec, plan, code) +- Running 3-way consultations (Gemini, Codex, Claude) +- Iterating based on feedback +- Enforcing phase transitions + +### Gates: When to STOP + +Porch has two human approval gates: + +| Gate | When | What to do | +|------|------|------------| +| `spec-approval` | After spec is written | **STOP** and wait | +| `plan-approval` | After plan is written | **STOP** and wait | + +When porch outputs: +``` +GATE: spec-approval +Human approval required. STOP and wait. +``` + +You must: +1. Output a clear message: "Spec ready for approval. Waiting for human." +2. **STOP working** +3. Wait for the human to run `porch approve XXXX spec-approval` +4. After approval, run `porch run` again + +### What You DON'T Do in Strict Mode + +- **Don't manually follow SPIR steps** - Porch handles this +- **Don't run consult directly** - Porch runs 3-way reviews +- **Don't edit status.yaml phase/iteration** - Only porch modifies state +- **Don't call porch approve** - Only humans approve gates +- **Don't skip gates** - Always stop and wait for approval + +## Soft Mode + +Spawned with: `af spawn XXXX --soft` or `af spawn --task "..."` + +In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly. + +### Startup Sequence + +```bash +# Read the spec and/or plan +cat codev/specs/XXXX-*.md +cat codev/plans/XXXX-*.md + +# Read the protocol +cat codev/protocols/spir/protocol.md + +# Start implementing +``` + +### The SPIR Protocol (Specify → Plan → Implement → Review) + +1. **Specify**: Read or create the spec at `codev/specs/XXXX-name.md` +2. **Plan**: Read or create the plan at `codev/plans/XXXX-name.md` +3. **Implement**: Write code following the plan phases +4. **Review**: Write lessons learned and create PR + +### Consultations + +Run 3-way consultations at checkpoints: +```bash +# After writing spec +consult -m gemini --protocol spir --type spec & +consult -m codex --protocol spir --type spec & +consult -m claude --protocol spir --type spec & +wait + +# After writing plan +consult -m gemini --protocol spir --type plan & +consult -m codex --protocol spir --type plan & +consult -m claude --protocol spir --type plan & +wait + +# After implementation +consult -m gemini --protocol spir --type pr & +consult -m codex --protocol spir --type pr & +consult -m claude --protocol spir --type pr & +wait +``` + +## Deliverables + +- Spec at `codev/specs/XXXX-name.md` +- Plan at `codev/plans/XXXX-name.md` +- Review at `codev/reviews/XXXX-name.md` +- Implementation code with tests +- PR ready for architect review + +## Communication + +### With the Architect + +If you're blocked or need help: +```bash +af send architect "Question about the spec..." +``` + +### Checking Status + +```bash +porch status # (strict mode) Your project status +af status # All builders +``` + +## Notifications + +**ALWAYS notify the architect** via `af send` at these key moments: + +| When | What to send | +|------|-------------| +| **Gate reached** | `af send architect "Project XXXX: ready for approval"` | +| **PR ready** | `af send architect "PR #N ready for review"` | +| **PR merged** | `af send architect "Project XXXX complete. PR merged. Ready for cleanup."` | +| **Blocked/stuck** | `af send architect "Blocked on X — need guidance"` | +| **Escalation needed** | `af send architect "Issue too complex — recommend escalating to SPIR/TICK"` | + +The architect may be working on other tasks and won't know you need attention unless you send a message. **Don't assume they're watching** — always notify explicitly. + +## When You're Blocked + +If you encounter issues you can't resolve: + +1. **Output a clear blocker message** describing the problem and options +2. **Use `af send architect "..."` to notify the Architect** +3. **Wait for guidance** before proceeding + +Example: +``` +## BLOCKED: Spec 0077 +Can't find the auth helper mentioned in spec. Options: +1. Create a new auth helper +2. Use a third-party library +3. Spec needs clarification +Waiting for Architect guidance. +``` + +## Constraints + +- **Stay in scope** - Only implement what's in the spec +- **Merge your own PRs** - After architect approves +- **Keep worktree clean** - No untracked files, no debug code +- **(Strict mode)** Run porch, don't bypass it +- **(Strict mode)** Stop at gates - Human approval is required +- **(Strict mode)** NEVER edit status.yaml directly +- **(Strict mode)** NEVER call porch approve diff --git a/codev/roles/consultant.md b/codev/roles/consultant.md new file mode 100644 index 0000000..bc8e2b6 --- /dev/null +++ b/codev/roles/consultant.md @@ -0,0 +1,33 @@ +# Role: Consultant + +You are a consultant providing a second perspective to support decision-making. + +## Responsibilities + +1. **Understand context** - Grasp the problem and constraints being presented +2. **Verify before flagging** - Check actual project files (package.json, configs) before claiming something is wrong or missing. Framework conventions change between major versions. +3. **Offer insights** - Provide alternatives or considerations that may have been missed +4. **Be constructive** - Help improve the solution, don't just critique +5. **Be direct** - Give honest, clear feedback without excessive hedging + +## You Are NOT + +- An adversary or gatekeeper +- A rubber stamp that just agrees +- A source of generic advice that ignores actual project context + +## Relationship to Other Roles + +| Role | Focus | +|------|-------| +| Architect | Orchestrates, decomposes, integrates | +| Builder | Implements in isolation | +| Consultant | Provides perspective, supports decisions | + +You think alongside the other agents, helping them see blind spots. You have filesystem access — use it to verify your claims against the actual codebase. + +## File Access Rules + +- **ALWAYS read files directly from disk** when reviewing specs, plans, or code. File paths are provided in the query — open and read them. +- **NEVER rely on `git diff` or `git log -p` as your primary review source.** Diffs are lossy, get truncated, and miss uncommitted work. Read the actual files instead. +- If you need to understand what changed, read the full file first, then optionally use `git diff` as a secondary reference. diff --git a/codev/specs/14-tick-001-jj-auto-install.md b/codev/specs/14-tick-001-jj-auto-install.md new file mode 100644 index 0000000..614a341 --- /dev/null +++ b/codev/specs/14-tick-001-jj-auto-install.md @@ -0,0 +1,73 @@ +# TICK 14-001: JJ Auto-Install CLI Command + +## Status +- **Protocol**: TICK +- **Amends**: Spec 14 (CLI) +- **Phase**: Specify + +## Problem + +`pip install fava-trails` does not provide JJ. Users hit an adoption cliff: + +1. `fava-trails bootstrap ` → "Error: jj not found. Install with: bash scripts/install-jj.sh" +2. `scripts/install-jj.sh` does not exist in the PyPI package +3. User must find JJ's website, figure out which binary to download, install manually +4. Error messages in `jj_backend.py` and `cli.py` still reference `scripts/install-jj.sh` + +This is three steps and a dead-end error between `pip install` and a working system. Gemini's assessment: "Complexity here kills adoption." + +## Amendment + +Add a `fava-trails install-jj` subcommand that downloads and installs the JJ binary. Update all error messages to reference it. + +### New: `fava-trails install-jj` + +Python reimplementation of `scripts/install-jj.sh`, cross-platform: + +- Detect OS + arch (Linux x86_64/aarch64, macOS x86_64/arm64) +- Download pre-built binary from `github.com/jj-vcs/jj/releases` +- Install to `~/.local/bin/jj` +- Verify binary runs (`jj version`) +- Version-aware skip: if installed version matches target, exit 0. If versions differ, proceed with install (enables upgrades via `--version`) +- Windows detection: print actionable `winget install Jujutsu.Jujutsu` command instead of generic error +- Post-install PATH check: verify `~/.local/bin` is in PATH, warn clearly if not +- Use `urllib` only — no new dependencies + +### Changed: Error messages + +All "jj not found" error messages updated to: + +``` +jj binary not found. Install with: fava-trails install-jj + Or manually from: https://jj-vcs.github.io/jj/ +``` + +Affected locations: +- `src/fava_trails/cli.py:212` — `cmd_bootstrap` +- `src/fava_trails/cli.py:427` — `cmd_doctor` +- `src/fava_trails/vcs/jj_backend.py:64` — `_find_jj` + +### Changed: `fava-trails bootstrap` + +When JJ is missing, instead of failing immediately, print: + +``` +JJ not found. Run 'fava-trails install-jj' first, or install manually from https://jj-vcs.github.io/jj/ +``` + +### Unchanged + +- `scripts/install-jj.sh` stays (for source-repo developers, CI) +- No new PyPI dependencies +- No bundled binaries + +## Success Criteria + +- `pip install fava-trails && fava-trails install-jj && fava-trails bootstrap ./data` works end-to-end +- Linux x86_64, Linux aarch64, macOS x86_64, macOS arm64 supported +- Existing tests pass; new tests cover `install-jj` subcommand +- Error messages no longer reference `scripts/install-jj.sh` + +## Scope + +< 200 LOC new code. No architecture changes. diff --git a/codev/templates/AGENTS.md b/codev/templates/AGENTS.md new file mode 100644 index 0000000..d66fd40 --- /dev/null +++ b/codev/templates/AGENTS.md @@ -0,0 +1,78 @@ +# {{PROJECT_NAME}} - AI Agent Instructions + +> **Note**: This file follows the [AGENTS.md standard](https://agents.md/) for cross-tool compatibility with Cursor, GitHub Copilot, and other AI coding assistants. A Claude Code-specific version is maintained in `CLAUDE.md`. + +## Project Overview + +This project uses **Codev** for AI-assisted development. + +## Available Protocols + +- **SPIR**: Multi-phase development with consultation (`codev/protocols/spir/protocol.md`) +- **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`) +- **TICK**: Fast autonomous implementation (`codev/protocols/tick/protocol.md`) +- **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`) +- **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`) + +## Key Locations + +- **Specs**: `codev/specs/` - Feature specifications (WHAT to build) +- **Plans**: `codev/plans/` - Implementation plans (HOW to build) +- **Reviews**: `codev/reviews/` - Reviews and lessons learned +- **Protocols**: `codev/protocols/` - Development protocols + +## Quick Start + +1. For new features, start with the Specification phase +2. Create exactly THREE documents per feature: spec, plan, and review +3. Follow the protocol phases as defined in the protocol files +4. Use multi-agent consultation when specified + +## File Naming Convention + +Use sequential numbering with descriptive names: +- Specification: `codev/specs/1-feature-name.md` +- Plan: `codev/plans/1-feature-name.md` +- Review: `codev/reviews/1-feature-name.md` + +## Git Workflow + +**NEVER use `git add -A` or `git add .`** - Always add files explicitly. + +Commit messages format: +``` +[Spec 1] Description of change +[Spec 1][Phase: implement] feat: Add feature +``` + +## CLI Commands + +Codev provides three CLI tools: + +- **codev**: Project management (init, adopt, update, doctor) +- **af**: Agent Farm orchestration (start, spawn, status, cleanup) +- **consult**: AI consultation for reviews (general, protocol, stats) + +For complete reference, see `codev/resources/commands/`: +- `codev/resources/commands/overview.md` - Quick start +- `codev/resources/commands/codev.md` - Project commands +- `codev/resources/commands/agent-farm.md` - Agent Farm commands +- `codev/resources/commands/consult.md` - Consultation commands + +## Configuration + +Agent Farm is configured via `af-config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`. + +```json +{ + "shell": { + "architect": "claude", + "builder": "claude", + "shell": "bash" + } +} +``` + +## For More Info + +Read the full protocol documentation in `codev/protocols/`. diff --git a/codev/templates/CLAUDE.md b/codev/templates/CLAUDE.md new file mode 100644 index 0000000..a895fd8 --- /dev/null +++ b/codev/templates/CLAUDE.md @@ -0,0 +1,76 @@ +# {{PROJECT_NAME}} - Claude Code Instructions + +## Project Overview + +This project uses **Codev** for AI-assisted development. + +## Available Protocols + +- **SPIR**: Multi-phase development with consultation (`codev/protocols/spir/protocol.md`) +- **ASPIR**: Autonomous SPIR — no human gates on spec/plan (`codev/protocols/aspir/protocol.md`) +- **TICK**: Fast autonomous implementation (`codev/protocols/tick/protocol.md`) +- **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`) +- **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`) + +## Key Locations + +- **Specs**: `codev/specs/` - Feature specifications (WHAT to build) +- **Plans**: `codev/plans/` - Implementation plans (HOW to build) +- **Reviews**: `codev/reviews/` - Reviews and lessons learned +- **Protocols**: `codev/protocols/` - Development protocols + +## Quick Start + +1. For new features, start with the Specification phase +2. Create exactly THREE documents per feature: spec, plan, and review +3. Follow the protocol phases as defined in the protocol files +4. Use multi-agent consultation when specified + +## File Naming Convention + +Use sequential numbering with descriptive names: +- Specification: `codev/specs/1-feature-name.md` +- Plan: `codev/plans/1-feature-name.md` +- Review: `codev/reviews/1-feature-name.md` + +## Git Workflow + +**NEVER use `git add -A` or `git add .`** - Always add files explicitly. + +Commit messages format: +``` +[Spec 1] Description of change +[Spec 1][Phase: implement] feat: Add feature +``` + +## CLI Commands + +Codev provides three CLI tools: + +- **codev**: Project management (init, adopt, update, doctor) +- **af**: Agent Farm orchestration (start, spawn, status, cleanup) +- **consult**: AI consultation for reviews (general, protocol, stats) + +For complete reference, see `codev/resources/commands/`: +- `codev/resources/commands/overview.md` - Quick start +- `codev/resources/commands/codev.md` - Project commands +- `codev/resources/commands/agent-farm.md` - Agent Farm commands +- `codev/resources/commands/consult.md` - Consultation commands + +## Configuration + +Agent Farm is configured via `af-config.json` at the project root. Created during `codev init` or `codev adopt`. Override via CLI flags: `--architect-cmd`, `--builder-cmd`, `--shell-cmd`. + +```json +{ + "shell": { + "architect": "claude", + "builder": "claude", + "shell": "bash" + } +} +``` + +## For More Info + +Read the full protocol documentation in `codev/protocols/`. diff --git a/codev/templates/arch.md b/codev/templates/arch.md new file mode 100644 index 0000000..ba5473e --- /dev/null +++ b/codev/templates/arch.md @@ -0,0 +1,56 @@ +# Architecture + +High-level architecture documentation for this project. Updated during MAINTAIN protocol runs. + +## Overview + + + +## Directory Structure + +``` +project-root/ +├── codev/ # Development methodology +│ ├── specs/ # Feature specifications +│ ├── plans/ # Implementation plans +│ └── reviews/ # Post-implementation reviews +└── [your code] # Project source code +``` + +## Key Components + + + +### Component 1 + +**Location**: `src/...` + +**Purpose**: ... + +**Key Files**: +- `file1.ts` - ... +- `file2.ts` - ... + +## Data Flow + + + +## External Dependencies + + + +| Dependency | Purpose | Documentation | +|------------|---------|---------------| +| Example | ... | [docs](url) | + +## Configuration + + + +## Conventions + + + +--- + +*Generated by MAINTAIN protocol. To update: run MAINTAIN or edit directly.* diff --git a/codev/templates/cheatsheet.md b/codev/templates/cheatsheet.md new file mode 100644 index 0000000..feaf0e3 --- /dev/null +++ b/codev/templates/cheatsheet.md @@ -0,0 +1,176 @@ +# Codev Cheatsheet + +A quick reference for Codev's philosophies, concepts, and tools. + +--- + +## Core Philosophies + +### 1. Natural Language is the Programming Language + +Specifications and plans are as important as code—they ARE the requirements and design. + +| Traditional | Codev | +|-------------|-------| +| Code first, document later | Spec first, code implements spec | +| Documentation gets stale | Specs ARE the source of truth | +| Humans read code to understand | AI agents translate spec → code | + +**Corollaries:** +- The spec IS the requirements; the plan IS the design +- Code is the implementation of well-defined natural language artifacts +- If the spec is wrong, the code will be wrong—fix the spec first + +### 2. Multiple Models Outperform a Single Model + +No single AI model catches everything. Diverse perspectives find more issues. + +| Role | Models | +|------|--------| +| Architect & Builder | Claude (primary agent) | +| Consultants | Gemini, Codex, Claude (for reviews) | + +**Corollaries:** +- 3-way reviews catch issues single models miss +- Different models have different strengths and blind spots +- Consultation happens at key checkpoints, not continuously + +### 3. Human-Agent Work Requires Thoughtful Structure + +Just like structuring a human team—clear roles, defined processes, explicit handoffs. + +| Component | Purpose | +|-----------|---------| +| Protocols | Define HOW work happens (SPIR, TICK, etc.) | +| Roles | Define WHO does what (Architect, Builder, Consultant) | +| Parallelism | Scale by running multiple builders simultaneously | + +**Corollaries:** +- Well-defined protocols reduce ambiguity and rework +- Clear roles enable autonomous operation +- Parallel execution multiplies throughput + +--- + +## Core Concepts + +### Protocols + +A **protocol** is a structured workflow that defines how work progresses from idea to completion. + +| Protocol | Use For | Phases | +|----------|---------|--------| +| **SPIR** | New features | Specify → Plan → Implement → Review | +| **TICK** | Amendments to existing specs | Task Identification → Coding → Kickout | +| **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync | +| **EXPERIMENT** | Research & prototyping | Hypothesis → Experiment → Conclude | + +### Roles + +A **role** defines who does what work and what tools/permissions they have. + +| Role | Responsibilities | +|------|------------------| +| **Architect** | Orchestrates development, writes specs/plans, reviews PRs, maintains big picture | +| **Builder** | Implements specs in isolated worktrees, writes tests, creates PRs | +| **Consultant** | External reviewers providing second opinions on specs, plans, implementations | + +**Consultant Flavors** (via `--type`): +- `spec` - Review specification completeness +- `plan` - Review implementation plan feasibility +- `impl` - Review code for spec adherence +- `pr` - Review pull request before merge +- `phase` - Phase-scoped review (builder only) +- `integration` - Review for architectural fit + +### Context Hierarchy + +In much the same way an operating system has a memory hierarchy, Codev repos have a context hierarchy. The codev/ directory holds the top 3 layers. This allows both humans and agents to think about problems at different levels of detail. + +**Key insight**: We build from the top down, and we propagate information from the bottom up. We start with an entry in the project list, then spec and plan out the feature, generate the code, and then propagate what we learned through the reviews. + +--- + +## Tools Reference + +### codev + +Project management commands. Typically used by **humans** to set up and maintain projects. + +| Command | Description | +|---------|-------------| +| `codev init ` | Create a new Codev project | +| `codev adopt` | Add Codev to an existing project | +| `codev doctor` | Check dependencies and configuration | +| `codev update` | Update Codev framework | +| `codev import` | Import specs from another project | + +### agent-farm (af) + +Architect-Builder orchestration. Used by both **humans and agents**—agents use it more frequently. + +| Command | Description | +|---------|-------------| +| `af workspace start` | Start workspace (port 4200, 4300, etc.) | +| `af workspace stop` | Stop all processes | +| `af spawn --protocol spir` | Spawn a builder for project | +| `af status` | Check status of all builders | +| `af send ` | Send message (builder↔architect) | +| `af cleanup -p ` | Clean up a builder worktree | +| `af shell` | Spawn a utility shell | +| `af open ` | Open file in workspace viewer | +| `af tower start` | Start cross-project tower | + +### consult + +Multi-agent consultation. Used by both humans and agents—**mostly agents** during reviews. + +| Command | Description | +|---------|-------------| +| `consult -m --prompt "text"` | General consultation | +| `consult -m --protocol spir --type spec` | Review a specification | +| `consult -m --protocol spir --type plan` | Review an implementation plan | +| `consult -m --protocol spir --type pr` | Review a pull request | +| `consult stats` | View consultation statistics | + +**Models**: `gemini` (alias: `pro`), `codex` (alias: `gpt`), `claude` (alias: `opus`) + +**Review Types** (via `--type` with `--protocol`): +| Type | Use Case | +|------|----------| +| `spec` | Review spec completeness and clarity | +| `plan` | Review plan coverage and feasibility | +| `impl` | Review implementation quality (Builder use) | +| `pr` | Review pull request before merge | +| `phase` | Phase-scoped review (Builder use) | +| `integration` | Review architectural fit (Architect use) | + +--- + +## Quick Reference + +### SPIR Checklist + +``` +[ ] Specify - Write spec in codev/specs/XXXX-name.md +[ ] Plan - Write plan in codev/plans/XXXX-name.md + For each phase of the plan: + [ ] Implement - Write code following the plan + [ ] Defend - Write tests for the implementation + [ ] Evaluate - Consult external reviewers, address feedback +[ ] Review - Write review in codev/reviews/XXXX-name.md, create PR +``` + +### Consultation Pattern + +```bash +# Run 3-way review in parallel +consult -m gemini --protocol spir --type pr & +consult -m codex --protocol spir --type pr & +consult -m claude --protocol spir --type pr & +wait +``` + +--- + +*For detailed documentation, see the full protocol files in `codev/protocols/`.* diff --git a/codev/templates/lessons-learned.md b/codev/templates/lessons-learned.md new file mode 100644 index 0000000..e205ede --- /dev/null +++ b/codev/templates/lessons-learned.md @@ -0,0 +1,28 @@ +# Lessons Learned + +> Extracted from `codev/reviews/`. Last updated: YYYY-MM-DD + +## Testing + + + +## Architecture + + + +## Process + + + +## Tooling + + + +## Integration + + + +--- + +*Generated by MAINTAIN protocol from review documents.* +*To add lessons: document them in review files, then run MAINTAIN.* diff --git a/codev/templates/lifecycle.md b/codev/templates/lifecycle.md new file mode 100644 index 0000000..98d5efd --- /dev/null +++ b/codev/templates/lifecycle.md @@ -0,0 +1,147 @@ +# Codev Project Lifecycle + +Every project in Codev flows through a series of stages from idea to production. This document explains each stage and how projects progress through the lifecycle. + +## Lifecycle Overview + +``` +conceived → specified → planned → implementing → implemented → committed → integrated +``` + +## Stages + +### 1. Conceived + +**What it means:** An idea has been captured. A spec file may exist but hasn't been approved yet. + +**Who does it:** Anyone can conceive a project by describing what they want to build. + +**What happens next:** The Architect (AI) writes a specification. The human reviews and approves it. + +**Artifact:** Draft specification in `codev/specs/NNN-name.md` + +--- + +### 2. Specified + +**What it means:** The specification has been approved by a human. + +**Who does it:** Only a human can approve a specification and mark it as specified. + +**What happens next:** The Architect creates an implementation plan. + +**Artifact:** Approved specification in `codev/specs/NNN-name.md` + +--- + +### 3. Planned + +**What it means:** An implementation plan exists that describes how to build the feature. + +**Who does it:** The Architect (AI) creates the plan, human reviews it. + +**What happens next:** A Builder is spawned to implement the plan. + +**Artifact:** Implementation plan in `codev/plans/NNN-name.md` + +--- + +### 4. Implementing + +**What it means:** Active development is in progress. A Builder is working on the code. + +**Who does it:** A Builder (AI agent) in an isolated git worktree. + +**What happens next:** Builder completes implementation and creates a PR. + +**Artifact:** Code changes in a builder worktree, work in progress + +--- + +### 5. Implemented + +**What it means:** Code is complete, tests pass, and a Pull Request has been created. + +**Who does it:** The Builder creates the PR after completing implementation. + +**What happens next:** The Architect reviews the PR, Builder addresses feedback, then merges. + +**Artifact:** Open Pull Request ready for review + +--- + +### 6. Committed + +**What it means:** The PR has been merged to the main branch. + +**Who does it:** The Builder merges after approval from the Architect's review. + +**What happens next:** Human validates in production and marks as integrated. + +**Artifact:** Merged PR, code on main branch + +--- + +### 7. Integrated + +**What it means:** The feature has been validated in production and the project is complete. + +**Who does it:** Only a human can mark a project as integrated after validating it works. + +**What happens next:** Nothing - the project is complete! A review document captures lessons learned. + +**Artifact:** Review document in `codev/reviews/NNN-name.md` + +--- + +## Terminal States + +Projects can also end up in terminal states if they won't be completed: + +### Abandoned + +The project was canceled or rejected. It will not be implemented. Close the GitHub Issue with a comment explaining why. + +### On-Hold + +The project is temporarily paused but may resume later. The notes field should explain the reason and any conditions for resuming. + +--- + +## Human Approval Gates + +Two stages require explicit human approval - AI agents cannot bypass these: + +| Gate | Transition | Why | +|------|------------|-----| +| **Spec Approval** | conceived → specified | Humans must approve what gets built | +| **Production Validation** | committed → integrated | Humans must verify it works in production | + +``` +conceived → [HUMAN APPROVES] → specified → planned → implementing → implemented → committed → [HUMAN VALIDATES] → integrated +``` + +--- + +## Managing Projects + +Project tracking uses **GitHub Issues**. To manage projects: + +- **Add a project:** Create a GitHub Issue describing what you want to build +- **Update status:** Update issue labels and comments as work progresses +- **Approve stages:** Review the spec/plan and tell the Architect to mark it approved +- **View progress:** Check the Work tab in the dashboard or `gh issue list` + +--- + +## Quick Reference + +| Stage | Artifact | Who Advances | +|-------|----------|--------------| +| Conceived | Draft spec | AI writes, human approves | +| Specified | Approved spec | AI creates plan | +| Planned | Implementation plan | AI spawns builder | +| Implementing | WIP code | Builder completes | +| Implemented | Open PR | Architect reviews, Builder merges | +| Committed | Merged PR | Human validates | +| Integrated | Review doc | Complete | diff --git a/codev/templates/pr-overview.md b/codev/templates/pr-overview.md new file mode 100644 index 0000000..faefc08 --- /dev/null +++ b/codev/templates/pr-overview.md @@ -0,0 +1,73 @@ +# PR Overview Template + +Use this template to prepare context for architect-mediated PR reviews. + +## PR Info +- **Number**: #NNN +- **Title**: [PR Title] +- **Branch**: [branch-name] +- **Author**: [author] +- **Spec**: [link to spec if applicable] +- **Plan**: [link to plan if applicable] + +## Summary + +[1-2 sentence summary of what this PR does and why] + +## Key Changes + +### File: `path/to/file1.ts` +**What**: [Brief description of changes] +**Why**: [Rationale for these changes] + +### File: `path/to/file2.ts` +**What**: [Brief description of changes] +**Why**: [Rationale for these changes] + +## Diff + +```diff +[Include the relevant portions of the diff, or full diff if small] +[For large PRs, focus on the most significant changes] +``` + +## Test Coverage + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing completed + +**Test summary**: [Brief description of test coverage] + +## Questions for Reviewer + +1. [Specific question about design decision] +2. [Question about edge case handling] +3. [Question about alternative approaches considered] + +## Context from Spec/Plan + +[Include relevant excerpts from the spec or plan that inform this PR] + +--- + +## Usage + +To use this template for architect-mediated reviews: + +```bash +# Fill out this template and save as overview.md, then: +consult -m gemini --type pr --context overview.md + +# Or pipe directly: +cat overview.md | consult -m gemini --type pr --context - + +# For 3-way parallel reviews: +consult -m gemini --type pr --context overview.md & +consult -m codex --type pr --context overview.md & +consult -m claude --type pr --context overview.md & +wait +``` + +The consultant will analyze the provided context WITHOUT accessing the filesystem, +resulting in faster and more consistent reviews. diff --git a/src/fava_trails/cli.py b/src/fava_trails/cli.py index c463a7b..306c900 100644 --- a/src/fava_trails/cli.py +++ b/src/fava_trails/cli.py @@ -3,9 +3,14 @@ from __future__ import annotations import argparse +import platform import shutil import subprocess import sys +import tarfile +import tempfile +import urllib.error +import urllib.request from pathlib import Path import yaml @@ -209,7 +214,7 @@ def cmd_bootstrap(args: argparse.Namespace) -> int: if not jj_bin: jj_bin = str(Path.home() / ".local" / "bin" / "jj") if not Path(jj_bin).exists(): - print("Error: jj not found. Install with: bash scripts/install-jj.sh", file=sys.stderr) + print("Error: jj not found. Install with: fava-trails install-jj\n Or manually: https://jj-vcs.github.io/jj/", file=sys.stderr) return 1 # Create directory @@ -424,7 +429,7 @@ def cmd_doctor(args: argparse.Namespace) -> int: any_failed = True else: print("JJ: NOT FOUND") - print(" Fix: bash scripts/install-jj.sh") + print(" Fix: fava-trails install-jj") any_failed = True # Check 2: Data repo valid? @@ -472,6 +477,122 @@ def cmd_doctor(args: argparse.Namespace) -> int: return 1 if any_failed else 0 +# ─── install-jj ─────────────────────────────────────────────────────────────── + +JJ_DEFAULT_VERSION = "0.28.0" +_JJ_INSTALL_DIR = Path.home() / ".local" / "bin" + + +def cmd_install_jj(args: argparse.Namespace) -> int: + """Download and install the Jujutsu (JJ) binary.""" + version = getattr(args, "jj_version", None) or JJ_DEFAULT_VERSION + + # Platform detection first — Windows requires a different installer + os_name = sys.platform # "linux", "darwin", "win32" + machine = platform.machine().lower() + + if os_name == "win32": + print("Windows detected. Install JJ with:") + print(" winget install Jujutsu.Jujutsu") + print("Or manually from: https://jj-vcs.github.io/jj/") + return 1 + + # Check if JJ is already installed at the target version + existing = shutil.which("jj") or str(_JJ_INSTALL_DIR / "jj") + if Path(existing).exists(): + try: + result = subprocess.run( + [existing, "--version"], + capture_output=True, + text=True, + timeout=5, + ) + installed_output = result.stdout.strip() + if f"jj {version}" in installed_output: + print(f"JJ already installed: {installed_output}") + return 0 + except (OSError, subprocess.TimeoutExpired): + pass + + if os_name == "linux": + if machine in ("x86_64", "amd64"): + suffix = "x86_64-unknown-linux-musl" + elif machine in ("aarch64", "arm64"): + suffix = "aarch64-unknown-linux-musl" + else: + print(f"Unsupported Linux architecture: {machine}", file=sys.stderr) + print("Install manually from: https://jj-vcs.github.io/jj/", file=sys.stderr) + return 1 + elif os_name == "darwin": + if machine in ("x86_64", "amd64"): + suffix = "x86_64-apple-darwin" + elif machine in ("arm64", "aarch64"): + suffix = "aarch64-apple-darwin" + else: + print(f"Unsupported macOS architecture: {machine}", file=sys.stderr) + print("Install manually from: https://jj-vcs.github.io/jj/", file=sys.stderr) + return 1 + else: + print(f"Unsupported OS: {os_name}", file=sys.stderr) + print("Install manually from: https://jj-vcs.github.io/jj/", file=sys.stderr) + return 1 + + url = f"https://github.com/jj-vcs/jj/releases/download/v{version}/jj-v{version}-{suffix}.tar.gz" + print(f"Downloading JJ v{version} for {suffix}...") + + with tempfile.TemporaryDirectory() as tmpdir: + tarball = Path(tmpdir) / "jj.tar.gz" + try: + with urllib.request.urlopen(url, timeout=30) as r, open(tarball, "wb") as f: + shutil.copyfileobj(r, f) + except (urllib.error.URLError, OSError) as e: + print(f"Error: download failed: {e}", file=sys.stderr) + return 1 + + with tarfile.open(tarball, "r:gz") as tf: + # Find the jj binary member + members = [m for m in tf.getmembers() if Path(m.name).name == "jj"] + if not members: + print("Error: jj binary not found in tarball", file=sys.stderr) + return 1 + member = members[0] + if not member.isfile(): + print("Error: jj entry in tarball is not a regular file", file=sys.stderr) + return 1 + # Safe extraction: read via extractfile(), write manually (avoids path traversal) + src_f = tf.extractfile(member) + if src_f is None: + print("Error: failed to read jj from tarball", file=sys.stderr) + return 1 + extracted = Path(tmpdir) / "jj" + with src_f, open(extracted, "wb") as dst_f: + shutil.copyfileobj(src_f, dst_f) + + try: + _JJ_INSTALL_DIR.mkdir(parents=True, exist_ok=True) + dest = _JJ_INSTALL_DIR / "jj" + shutil.copy2(extracted, dest) + dest.chmod(0o755) + except OSError as e: + print(f"Error: failed to install JJ to {dest}: {e}", file=sys.stderr) + return 1 + + # Verify + try: + result = subprocess.run([str(dest), "--version"], capture_output=True, text=True, timeout=5) + print(f"Installed: {result.stdout.strip()}") + except Exception as e: + print(f"Warning: install completed but verification failed: {e}", file=sys.stderr) + + # PATH check + if not shutil.which("jj"): + print(f"\nWarning: {_JJ_INSTALL_DIR} is not in your PATH.") + print("Add it with:") + print(f' echo \'export PATH="$HOME/.local/bin:$PATH"\' >> ~/.bashrc && source ~/.bashrc') + + return 0 + + # ─── Argument parser ────────────────────────────────────────────────────────── @@ -523,6 +644,17 @@ def build_parser() -> argparse.ArgumentParser: p_doctor = subparsers.add_parser("doctor", help="Check JJ, data repo, and scope configuration") p_doctor.set_defaults(func=cmd_doctor) + # install-jj + p_install_jj = subparsers.add_parser("install-jj", help="Download and install the Jujutsu (JJ) binary") + p_install_jj.add_argument( + "--version", + dest="jj_version", + default=None, + metavar="VERSION", + help=f"JJ version to install (default: {JJ_DEFAULT_VERSION})", + ) + p_install_jj.set_defaults(func=cmd_install_jj) + return parser diff --git a/src/fava_trails/vcs/jj_backend.py b/src/fava_trails/vcs/jj_backend.py index 36653b4..cf4c1b4 100644 --- a/src/fava_trails/vcs/jj_backend.py +++ b/src/fava_trails/vcs/jj_backend.py @@ -62,7 +62,7 @@ def _find_jj() -> str: if local_jj.exists(): return str(local_jj) raise FileNotFoundError( - "jj binary not found. Install from https://jj-vcs.github.io/jj/ or run scripts/install-jj.sh (from source repo)" + "jj binary not found. Install with: fava-trails install-jj (or manually from https://jj-vcs.github.io/jj/)" ) async def _run(self, *args: str, check: bool = True) -> tuple[str, str]: diff --git a/tests/conftest.py b/tests/conftest.py index 5235ef2..30fd874 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -11,7 +11,7 @@ # Skip all tests if jj is not installed jj_bin = shutil.which("jj") or str(Path.home() / ".local" / "bin" / "jj") if not Path(jj_bin).exists(): - pytest.skip("jj binary not found — install via scripts/install-jj.sh", allow_module_level=True) + pytest.skip("jj binary not found — install via: fava-trails install-jj", allow_module_level=True) @pytest.fixture diff --git a/tests/test_cli.py b/tests/test_cli.py index e1317de..a8ec0b4 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -20,6 +20,7 @@ cmd_bootstrap, cmd_doctor, cmd_init, + cmd_install_jj, cmd_scope, cmd_scope_list, cmd_scope_set, @@ -474,7 +475,7 @@ def exists_side_effect(self): assert rc == 1 out = capsys.readouterr().out assert "NOT FOUND" in out - assert "install-jj.sh" in out + assert "install-jj" in out def test_doctor_missing_data_repo(tmp_path, monkeypatch, capsys): @@ -536,3 +537,139 @@ def test_bootstrap_refuses_existing_config(tmp_path): rc = cmd_bootstrap(args) assert rc == 1 + +# ─── install-jj tests ───────────────────────────────────────────────────────── + + +def _make_install_jj_args(version=None): + args = MagicMock() + args.jj_version = version + return args + + +def test_install_jj_skips_if_version_matches(tmp_path, capsys): + """install-jj exits 0 without downloading when the installed version matches.""" + jj_bin = str(tmp_path / "jj") + Path(jj_bin).touch() + + mock_result = MagicMock() + mock_result.stdout = "jj 0.28.0\n" + mock_result.returncode = 0 + + with patch("shutil.which", return_value=jj_bin): + with patch("subprocess.run", return_value=mock_result): + rc = cmd_install_jj(_make_install_jj_args()) + + assert rc == 0 + out = capsys.readouterr().out + assert "already installed" in out + + +def test_install_jj_unsupported_platform(capsys): + """install-jj exits 1 on Windows and prints winget instructions.""" + with patch("sys.platform", "win32"): + with patch("shutil.which", return_value=None): + rc = cmd_install_jj(_make_install_jj_args()) + + assert rc == 1 + out = capsys.readouterr().out + assert "winget" in out + + +def test_install_jj_unsupported_arch(capsys): + """install-jj exits 1 on unsupported Linux architecture.""" + with patch("sys.platform", "linux"): + with patch("platform.machine", return_value="mips"): + with patch("shutil.which", return_value=None): + with patch("subprocess.run", side_effect=OSError("no jj")): + rc = cmd_install_jj(_make_install_jj_args()) + + assert rc == 1 + err = capsys.readouterr().err + assert "Unsupported" in err + + +def _make_fake_tarball(jj_data: bytes = b"#!/bin/sh\necho jj") -> bytes: + """Create an in-memory .tar.gz containing a 'jj' binary.""" + import io + import tarfile as _tarfile + + buf = io.BytesIO() + with _tarfile.open(fileobj=buf, mode="w:gz") as tf: + info = _tarfile.TarInfo(name="jj") + info.size = len(jj_data) + tf.addfile(info, io.BytesIO(jj_data)) + return buf.getvalue() + + +def _fake_urlopen(fake_bytes: bytes): + """Return a context-manager mock for urllib.request.urlopen.""" + import io + + class FakeResponse: + def read(self, n=-1): + return self._buf.read(n) + + def __enter__(self): + self._buf = io.BytesIO(fake_bytes) + return self + + def __exit__(self, *a): + pass + + return FakeResponse() + + +def test_install_jj_downloads_and_installs(tmp_path, capsys): + """install-jj downloads tarball, extracts binary, and verifies installation.""" + fake_bytes = _make_fake_tarball(b"#!/bin/sh\necho jj 0.28.0") + install_dir = tmp_path / ".local" / "bin" + install_dir.mkdir(parents=True) + + mock_run_result = MagicMock() + mock_run_result.stdout = "jj 0.28.0\n" + mock_run_result.returncode = 0 + + with patch("shutil.which", return_value=None): + with patch("fava_trails.cli._JJ_INSTALL_DIR", install_dir): + with patch("urllib.request.urlopen", return_value=_fake_urlopen(fake_bytes)): + with patch("subprocess.run", return_value=mock_run_result): + rc = cmd_install_jj(_make_install_jj_args()) + + assert rc == 0 + assert (install_dir / "jj").exists() + + +def test_install_jj_custom_version(tmp_path, capsys): + """install-jj uses --version argument in the download URL.""" + captured_urls = [] + fake_bytes = _make_fake_tarball() + install_dir = tmp_path / ".local" / "bin" + install_dir.mkdir(parents=True) + + def fake_urlopen(url, timeout=None): + captured_urls.append(url) + return _fake_urlopen(fake_bytes) + + mock_run_result = MagicMock() + mock_run_result.stdout = "jj 0.29.0\n" + + with patch("shutil.which", return_value=None): + with patch("fava_trails.cli._JJ_INSTALL_DIR", install_dir): + with patch("urllib.request.urlopen", side_effect=fake_urlopen): + with patch("subprocess.run", return_value=mock_run_result): + rc = cmd_install_jj(_make_install_jj_args(version="0.29.0")) + + assert rc == 0 + assert len(captured_urls) == 1 + assert "0.29.0" in captured_urls[0] + + +def test_install_jj_in_help(capsys): + """install-jj subcommand appears in fava-trails --help output.""" + result = subprocess.run( + [sys.executable, "-m", "fava_trails.cli", "--help"], + capture_output=True, + text=True, + ) + assert "install-jj" in result.stdout