Development Cycle

Standard Flow

Research → Dev → KB → QA

User gates every phase transition. Sequential execution — one agent at a time.

User + Manager: plan and prioritize (manager owns kanban)
    ↓
Phase 1: Research
    ↓ (user gates)
Phase 2: Dev (architecture → code → review)
    ↓ (user gates)
Phase 3: KB (cards, API docs, then fine-tune tex)
    ↓ (user gates)
Phase 4: QA (full regression, full benchmark)
    ↓ (user gates)
Done (or feedback loop)

Phase 1: Research

Team: Research. Agents: research-developer → research-reviewer.

• Check the reference library (library/INDEX.md) for relevant papers
• Investigate the problem: literature survey, mathematical analysis, proofs
• Cite library references using [library:{key}] notation
• Reviewer challenges every claim, verifies proofs
• Output lands in KB as idea cards or tex drafts (informal, no code backing)
• Suggest new references for kb-developer to add to the library
• User reviews tex for math correctness

KB artifact maturity

Maturity	What	Backed by code?
Idea card	Research finding, conjecture, literature note	No
Tex draft	Mathematical derivation, proof, algorithm sketch	No
Formal card	Full KB card with all sections	Yes
Formal tex	Polished math doc connected to implementation	Yes

Research produces idea cards and tex drafts. KB-dev promotes them to formal artifacts after code exists.

Phase 2: Dev

Team: Dev. Agents: architect-developer → architect-reviewer, then code-developer → code-reviewer.

Architecture

• Translate research into implementation plan
• Identify which files/functions to modify or create
• Produce: implementation locators, interface specs, refactoring plans
• Reviewer checks completeness, minimality, safety

Code

Code-developer:

• Implement according to the architecture spec
• Add @code-change tags to API doc blocks (Doxygen or docstrings; see Code-to-Docs Bridge)
• Compile and run basic smoke tests
• Hand off to code-reviewer

Code-reviewer (blocker):

1. Review: Correctness, style, @code-change tags, architecture conformance
2. Small regression test with early stop: Run a small test set. Stop at first failure. Any failure → REJECT.

Code-reviewer blocks merge on issues

Without this gate, developers prioritize deliverables over safety and performance.

Phase 3: KB

Team: KB. Agents: kb-developer → kb-reviewer.

Two sub-phases:

3a: Cards and API Documentation

• Process @code-change tags left by code-developer
• Write or update formal cards (one per source file)
• Write or update API documentation (Doxygen annotations or Sphinx docstrings)
• Update INDEX and SYNCLOG

3b: Fine-tune tex (wrap-up)

• Promote idea cards and tex drafts from research to formal status
• Connect math to actual implementation (reference real functions, constants, thresholds)
• Polish derivations, add code references
• User reviews tex for math correctness

KB-reviewer produces board view with Quality/Coverage/Consistency/Freshness scores after each sub-phase.

Phase 4: QA

Team: QA. Agent: benchmark.

• Run full regression test suite (complete, no early stop)
• Run full benchmark suite
• Compare against baseline
• Produce: performance report, regression verdict (PASS/WATCH/REGRESSED/CRITICAL)
• REGRESSED or CRITICAL blocks release

Reviewer vs QA testing

	Code-reviewer (Phase 2)	QA (Phase 4)
Test set	Small	Full
Early stop	Yes	No
When	Every code change	Pre-release / on demand
Blocks	Merge	Release

Shadow Flow (on demand)

Agents: shadow-developer → shadow-reviewer.

Activated when the manager or user wants to validate KB quality. Not part of the standard flow — runs separately.

Manager assigns module
    ↓
Shadow-dev reimplements from KB (no source access)
    ↓
Shadow-rev compares, produces gap report + code improvement report
    ↓
Findings route to:
    KB gaps       → kb-developer
    Code fixes    → code-developer
    Merge decision → user

See Shadow Validation for the full protocol.

---

Cross-Team Handoffs

From	To	Mechanism
research → KB	Idea cards and tex drafts land in KB
research → dev	Manager presents research output for architecture
architect → code	Implementation locator / interface spec
code → KB	@code-change tags in API docs (see Code-to-Docs Bridge)
KB → QA	After KB phase complete, QA runs full suite
QA → dev	Regression report triggers investigation
shadow-rev → KB	KB gap report with actionable fixes
shadow-rev → dev	Code improvement findings

---

Abbreviated Cycles

Task type	Phases needed
Bug fix (known cause)	Dev → KB → QA
New algorithm	Research → Dev → KB → QA
Refactoring	Dev → KB → QA
Documentation only	KB only
Performance investigation	QA → Research
KB validation	Shadow only

---

Feedback Loop

Research → Dev → KB → QA
    ↑                  |
    └── feedback ──────┘

• QA results may trigger research (unexpected numerical behavior)
• KB review may reveal research gaps (undocumented design rationale)
• Code review may trigger architecture changes (infeasible design)
• Shadow may reveal KB gaps or code improvements

---

Execution Model

Sequential only. No parallel work. One agent works at a time. User gates every phase. Manager owns the kanban and tracks progress.

See Sprint & Kanban for the kanban format.