Skip to content

Commit ff8eb09

Browse files
waleedkadouswaleedkadous
committed
Add codev project management framework
Includes protocols (SPIR, tick, bugfix, experiment, maintain), role definitions, resource docs, templates, and project configuration.
1 parent 2681d4e commit ff8eb09

69 files changed

Lines changed: 8908 additions & 1 deletion

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# ansari-backend - AI Agent Instructions
2+
3+
> **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`.
4+
5+
## Project Overview
6+
7+
This project uses **Codev** for AI-assisted development.
8+
9+
## Available Protocols
10+
11+
- **SPIR**: Multi-phase development with consultation (`codev/protocols/spir/protocol.md`)
12+
- **TICK**: Fast autonomous implementation (`codev/protocols/tick/protocol.md`)
13+
- **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
14+
- **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
15+
16+
## Key Locations
17+
18+
- **Specs**: `codev/specs/` - Feature specifications (WHAT to build)
19+
- **Plans**: `codev/plans/` - Implementation plans (HOW to build)
20+
- **Reviews**: `codev/reviews/` - Reviews and lessons learned
21+
- **Protocols**: `codev/protocols/` - Development protocols
22+
23+
## Quick Start
24+
25+
1. For new features, start with the Specification phase
26+
2. Create exactly THREE documents per feature: spec, plan, and review
27+
3. Follow the protocol phases as defined in the protocol files
28+
4. Use multi-agent consultation when specified
29+
30+
## File Naming Convention
31+
32+
Use sequential numbering with descriptive names:
33+
- Specification: `codev/specs/0001-feature-name.md`
34+
- Plan: `codev/plans/0001-feature-name.md`
35+
- Review: `codev/reviews/0001-feature-name.md`
36+
37+
## Git Workflow
38+
39+
**NEVER use `git add -A` or `git add .`** - Always add files explicitly.
40+
41+
Commit messages format:
42+
```
43+
[Spec 0001] Description of change
44+
[Spec 0001][Phase: implement] feat: Add feature
45+
```
46+
47+
## CLI Commands
48+
49+
Codev provides three CLI tools:
50+
51+
- **codev**: Project management (init, adopt, update, doctor)
52+
- **af**: Agent Farm orchestration (start, spawn, status, cleanup)
53+
- **consult**: AI consultation for reviews (pr, spec, plan)
54+
55+
For complete reference, see `codev/resources/commands/`:
56+
- `codev/resources/commands/overview.md` - Quick start
57+
- `codev/resources/commands/codev.md` - Project commands
58+
- `codev/resources/commands/agent-farm.md` - Agent Farm commands
59+
- `codev/resources/commands/consult.md` - Consultation commands
60+
61+
## Configuration
62+
63+
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`.
64+
65+
```json
66+
{
67+
"shell": {
68+
"architect": "claude",
69+
"builder": "claude",
70+
"shell": "bash"
71+
}
72+
}
73+
```
74+
75+
## For More Info
76+
77+
Read the full protocol documentation in `codev/protocols/`.

‎CLAUDE.md‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,37 @@
11
# Ansari Backend - Developer Guide
22

3+
## Project Overview
4+
5+
This project uses **Codev** for AI-assisted development.
6+
7+
## Available Protocols
8+
9+
- **SPIR**: Multi-phase development with consultation (`codev/protocols/spir/protocol.md`)
10+
- **TICK**: Fast autonomous implementation (`codev/protocols/tick/protocol.md`)
11+
- **EXPERIMENT**: Disciplined experimentation (`codev/protocols/experiment/protocol.md`)
12+
- **MAINTAIN**: Codebase maintenance (`codev/protocols/maintain/protocol.md`)
13+
14+
## Key Locations
15+
16+
- **Specs**: `codev/specs/` - Feature specifications (WHAT to build)
17+
- **Plans**: `codev/plans/` - Implementation plans (HOW to build)
18+
- **Reviews**: `codev/reviews/` - Reviews and lessons learned
19+
- **Protocols**: `codev/protocols/` - Development protocols
20+
21+
## Quick Start
22+
23+
1. For new features, start with the Specification phase
24+
2. Create exactly THREE documents per feature: spec, plan, and review
25+
3. Follow the protocol phases as defined in the protocol files
26+
4. Use multi-agent consultation when specified
27+
28+
## File Naming Convention
29+
30+
Use sequential numbering with descriptive names:
31+
- Specification: `codev/specs/0001-feature-name.md`
32+
- Plan: `codev/plans/0001-feature-name.md`
33+
- Review: `codev/reviews/0001-feature-name.md`
34+
335
## Branch Management
436
- Always create new branches from the `develop` branch, NOT from `main`
537
- Use descriptive branch names that reflect the feature or fix being implemented
@@ -20,6 +52,11 @@
2052
- Always run `ruff check` and `ruff format` before committing changes
2153
- Fix all linting errors - clean code is maintainable code
2254
- All PRs should target the `develop` branch, not `main`
55+
- Codev commit messages format:
56+
```
57+
[Spec 0001] Description of change
58+
[Spec 0001][Phase: implement] feat: Add feature
59+
```
2360

2461
## Branch Management Details
2562
- Consider a merged branch "done" - do not add new changes to it
@@ -107,4 +144,36 @@
107144
- Add tests for new functionality in the appropriate directory
108145
- Use fixture factories to keep tests maintainable
109146
- Test both happy path and error conditions
110-
- Keep tests independent (no dependencies between test functions)
147+
- Keep tests independent (no dependencies between test functions)
148+
149+
## CLI Commands
150+
151+
Codev provides three CLI tools:
152+
153+
- **codev**: Project management (init, adopt, update, doctor)
154+
- **af**: Agent Farm orchestration (start, spawn, status, cleanup)
155+
- **consult**: AI consultation for reviews (pr, spec, plan)
156+
157+
For complete reference, see `codev/resources/commands/`:
158+
- `codev/resources/commands/overview.md` - Quick start
159+
- `codev/resources/commands/codev.md` - Project commands
160+
- `codev/resources/commands/agent-farm.md` - Agent Farm commands
161+
- `codev/resources/commands/consult.md` - Consultation commands
162+
163+
## Configuration
164+
165+
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`.
166+
167+
```json
168+
{
169+
"shell": {
170+
"architect": "claude",
171+
"builder": "claude",
172+
"shell": "bash"
173+
}
174+
}
175+
```
176+
177+
## For More Info
178+
179+
Read the full protocol documentation in `codev/protocols/`.

‎af-config.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"shell": {
3+
"architect": "claude",
4+
"builder": "claude",
5+
"shell": "bash"
6+
}
7+
}

‎codev/consult-types/impl-review.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Implementation Review Prompt
2+
3+
## Context
4+
You are reviewing implementation work at Stage 4 (IMPLEMENTING) of the workflow. A builder has completed a phase (Implement + Defend) and needs feedback before proceeding. Your job is to verify the implementation matches the spec and plan.
5+
6+
## Focus Areas
7+
8+
1. **Spec Adherence**
9+
- Does the implementation fulfill the spec requirements for this phase?
10+
- Are acceptance criteria met?
11+
- Are there deviations from the spec that need explanation?
12+
13+
2. **Code Quality**
14+
- Is the code readable and maintainable?
15+
- Are there obvious bugs or issues?
16+
- Are error cases handled appropriately?
17+
- Does it follow project conventions?
18+
19+
3. **Test Coverage**
20+
- Are the tests adequate for this phase?
21+
- Do tests cover the main paths AND edge cases?
22+
- Are tests testing the right things (behavior, not implementation)?
23+
- Would the tests catch regressions?
24+
25+
4. **Plan Alignment**
26+
- Does the implementation follow the plan?
27+
- Are there deviations that make sense?
28+
- Are there plan items skipped or partially completed?
29+
30+
5. **UX Verification** (if spec has UX requirements)
31+
- Does the actual user experience match what the spec describes?
32+
- If spec says "async" or "non-blocking", is it actually async?
33+
- If spec says "immediate response", does user get one quickly?
34+
- Do any flow diagrams in the spec match the actual behavior?
35+
- **CRITICAL:** A synchronous implementation that passes tests can completely fail UX requirements
36+
37+
## Verdict Format
38+
39+
After your review, provide your verdict in exactly this format:
40+
41+
```
42+
---
43+
VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
44+
SUMMARY: [One-line summary of your assessment]
45+
CONFIDENCE: [HIGH | MEDIUM | LOW]
46+
---
47+
KEY_ISSUES:
48+
- [Issue 1 or "None"]
49+
- [Issue 2]
50+
...
51+
```
52+
53+
**Verdict meanings:**
54+
- `APPROVE`: Phase is complete, builder can proceed
55+
- `REQUEST_CHANGES`: Issues that must be fixed before proceeding
56+
- `COMMENT`: Minor suggestions, can proceed but note feedback
57+
58+
## Notes
59+
60+
- This is a phase-level review, not the final PR review
61+
- Focus on "does this phase work" not "is the whole feature done"
62+
- If referencing line numbers, use `file:line` format
63+
- The builder needs actionable feedback to continue

‎codev/consult-types/integration-review.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Integration Review Prompt
2+
3+
## Context
4+
You are performing an integration review at Stage 6 (COMMITTED) of the workflow. 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.
5+
6+
## Focus Areas
7+
8+
1. **Architectural Fit**
9+
- Does this change follow existing patterns in the codebase?
10+
- Are there inconsistencies with how similar things are done elsewhere?
11+
- Does it introduce new patterns that should be adopted more broadly?
12+
- Are dependencies appropriate and minimal?
13+
14+
2. **System Impact**
15+
- What other parts of the system might be affected?
16+
- Are there potential side effects not addressed?
17+
- Does this break any existing functionality?
18+
- Are there performance implications?
19+
20+
3. **API/Interface Quality**
21+
- Are new interfaces well-designed and consistent?
22+
- Will this be easy for other developers to use?
23+
- Is it properly documented for consumers?
24+
- Does it follow existing conventions?
25+
26+
4. **Maintenance Burden**
27+
- Is this code maintainable by others?
28+
- Are there any "clever" solutions that should be simplified?
29+
- Is the complexity justified?
30+
- Will this be easy to debug when issues arise?
31+
32+
5. **Migration/Compatibility**
33+
- Are there backward compatibility concerns?
34+
- Is migration path clear for existing users?
35+
- Are breaking changes properly communicated?
36+
37+
6. **UX Verification** (if spec has UX requirements)
38+
- Does the actual user experience match what the spec describes?
39+
- Compare spec's "Goals" section and flow diagrams to actual behavior
40+
- If spec says "async/non-blocking", verify the code is actually async
41+
- If spec says "immediate response", verify user isn't blocked waiting
42+
- **CRITICAL:** Tests passing does NOT mean UX requirements are met - verify manually
43+
44+
## Verdict Format
45+
46+
After your review, provide your verdict in exactly this format:
47+
48+
```
49+
---
50+
VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
51+
SUMMARY: [One-line summary of your assessment]
52+
CONFIDENCE: [HIGH | MEDIUM | LOW]
53+
---
54+
KEY_ISSUES:
55+
- [Issue 1 or "None"]
56+
- [Issue 2]
57+
...
58+
59+
INTEGRATION_NOTES:
60+
- [Note about system integration]
61+
- [Note about follow-up work needed]
62+
```
63+
64+
**Verdict meanings:**
65+
- `APPROVE`: Ready to merge
66+
- `REQUEST_CHANGES`: Integration issues that must be addressed
67+
- `COMMENT`: Suggestions for improvement, can merge but consider feedback
68+
69+
## Notes
70+
71+
- The implementation has already been reviewed - don't re-review code quality
72+
- Focus on "how does this fit the system" not "does this work"
73+
- Consider: Will I regret merging this in 6 months?
74+
- If requesting changes, be specific about what needs to change
75+
- INTEGRATION_NOTES can include suggestions for follow-up specs

‎codev/consult-types/plan-review.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Plan Review Prompt
2+
3+
## Context
4+
You are reviewing an implementation plan at Stage 2 (SPECIFIED) of the workflow. The spec has been approved - now you must evaluate whether the plan adequately describes HOW to implement it.
5+
6+
## Focus Areas
7+
8+
1. **Spec Coverage**
9+
- Does the plan address all requirements in the spec?
10+
- Are there spec requirements not covered by any phase?
11+
- Are there phases that go beyond the spec scope?
12+
13+
2. **Phase Breakdown**
14+
- Are phases appropriately sized (not too large or too small)?
15+
- Is the sequence logical (dependencies respected)?
16+
- Can each phase be completed and committed independently?
17+
18+
3. **Technical Approach**
19+
- Is the implementation approach sound?
20+
- Are the right files/modules being modified?
21+
- Are there obvious better approaches being missed?
22+
23+
4. **Testability**
24+
- Does each phase have clear test criteria?
25+
- Will the Defend step (writing tests) be feasible?
26+
- Are edge cases from the spec addressable?
27+
28+
5. **Risk Assessment**
29+
- Are there potential blockers not addressed?
30+
- Are dependencies on other systems identified?
31+
- Is the plan realistic given constraints?
32+
33+
## Verdict Format
34+
35+
After your review, provide your verdict in exactly this format:
36+
37+
```
38+
---
39+
VERDICT: [APPROVE | REQUEST_CHANGES | COMMENT]
40+
SUMMARY: [One-line summary of your assessment]
41+
CONFIDENCE: [HIGH | MEDIUM | LOW]
42+
---
43+
KEY_ISSUES:
44+
- [Issue 1 or "None"]
45+
- [Issue 2]
46+
...
47+
```
48+
49+
**Verdict meanings:**
50+
- `APPROVE`: Plan is ready for human review
51+
- `REQUEST_CHANGES`: Significant issues with approach or coverage
52+
- `COMMENT`: Minor suggestions, plan is workable but could improve
53+
54+
## Notes
55+
56+
- The spec has already been approved - don't re-litigate spec decisions
57+
- Focus on the quality of the plan as a guide for builders
58+
- Consider: Would a builder be able to follow this plan successfully?
59+
- If referencing existing code, verify file paths seem accurate

0 commit comments

Comments
 (0)