Citadel Agile Methodology

The Citadel methodology enables iterative, AI-assisted implementation with spec-driven development, INVEST quality scoring, mandatory MCP validation, TDD workflows, ADR enforcement, and built-in learning loops.

Core Principles

1. Single-Task Iterations: One task at a time - the smallest testable unit of work
2. INVEST Quality: All tasks scored 0-12; must achieve >= 7/12 before implementation
3. EARS Patterns: Requirements use EARS syntax for unambiguous specification
4. ADR Enforcement: Architecture decisions enforced via fitness functions (BLOCKING)
5. MCP-First Validation: Always validate tech stack against MCP servers before coding
6. TDD Workflow: RED → GREEN → REFACTOR for all code changes
7. Progressive Enhancement: Spec quality improves automatically as tasks execute
8. Manual Recovery: On failure, halt and present options (no auto-retry)
9. Retrospectives: Capture learnings after each completed task
10. Phase Gates: Explicit checklists for phase transitions

INVEST Scoring

Every task is scored on 6 criteria (0-2 points each):

Criterion	2 Points	1 Point	0 Points
Independent	No dependencies / all complete	1-2 incomplete deps	3+ incomplete deps
Negotiable	AC focuses on outcomes	Some impl details	Prescriptive/vague
Valuable	Maps to FR/NFR/SEC	Infrastructure/enabler	No traceability
Estimable	Complexity + hours + verification	Partial fields	Missing fields
Small	Within tier hours	At tier boundary	Exceeds tier
Testable	3+ AC checkboxes + verification	1-2 checkboxes	No AC section

Threshold: >= 7/12 to proceed with implementation

Scripts:

• pwsh .work/scripts/Add-InvestScore.ps1 - Calculate and add scores
• pwsh .work/scripts/Test-InvestScore.ps1 - Validate scores

Spec-Driven Development

The Citadel methodology integrates spec-driven development to ensure autonomous AI implementation produces correct, consistent results.

EARS Patterns

Requirements use EARS (Easy Approach to Requirements Syntax) for unambiguous specification:

Pattern	Syntax	Use Case
Ubiquitous	"The system SHALL..."	Always-true behavior
Event-Driven	"WHEN x, the system SHALL..."	Triggered behavior
State-Driven	"WHILE x, the system SHALL..."	State-dependent behavior
Unwanted Behavior	"IF x (unwanted), the system SHALL..."	Exception handling
Optional Feature	"WHERE x is supported, the system SHALL..."	Conditional features
Complex	Combination of patterns	Multi-condition behavior

Schema: .work/schemas/ears-requirement.schema.json

ADR Enforcement (BLOCKING)

Architecture Decision Records are enforced via NetArchTest fitness functions:

/citadel-next Phase 7.2: ADR COMPLIANCE CHECK

1. Extract ADRs from task.adr_refs[]
2. Run: dotnet test --filter "ADR={ADR-IDs}"
3. If ANY test fails: BLOCK task completion

⛔ ADR VIOLATION DETECTED
   ADR: ADR-023 (Modular Monolith)
   Rule: Domain must not depend on Infrastructure
   Violation: Citadel.Orchestration.Domain.Agent references EF Core
   Fix: Move data access to Infrastructure layer

Schema: .work/schemas/adr-fitness.schema.json

Progressive Spec Enhancement

Rather than upfront migration, specs improve automatically via /citadel-next Phase 4.5:

Phase 4.5: PROGRESSIVE SPEC ENHANCEMENT

For each task executed:
1. Check requirements for EARS patterns → Auto-generate if missing
2. Check requirements for INVEST scores → Block if < 7
3. Check ADRs for fitness functions → Auto-generate if missing
4. Auto-generate Gherkin feature files from acceptance criteria

Result: Spec quality improves naturally as work progresses

Spec Validation Commands

Command	Purpose
/citadel-audit --ears	Validate EARS patterns in requirements
/citadel-audit --gherkin	Validate Gherkin syntax in feature files
/citadel-audit --adr	Run ADR fitness functions
/citadel-audit --drift	Detect specification drift
/citadel-audit --specs	All spec-driven validations
/citadel-spec-check	Pre-flight spec quality check

Traceability

Full bidirectional traceability is maintained:

Requirement (FR-042)
    ↓ ears_pattern, invest_score
    ↓ addressed_by_tasks[]
Task (TSK-108-01)
    ↓ requirements_addressed[], adr_refs[]
    ↓ gherkin_scenarios[]
Feature File (CacheEviction.feature)
    ↓ @TSK-108-01 @FR-042 tags
Test Results (living documentation)

Available Commands

Command	Purpose	When to Use
/citadel-session	Initialize implementation session	Start of every session
/citadel-status	View progress and next steps	Check current state
/citadel-audit	Validate .work folder integrity	Before implementation
/citadel-spec-check	Pre-flight spec quality check	Preview spec issues
/citadel-iterate	Execute full TDD cycle with retro	Primary workflow
/citadel-next	Direct task execution (with spec enhancement)	Quick execution
/citadel-work	Automatic work selection	Unified workflow

Recommended Workflow

Session Start

1. /citadel-session     # Load context, verify environment
2. /citadel-status      # Review current position
3. /citadel-audit       # Validate .work folder (optional if recent)

Single-Task Iteration (Primary Pattern)

/citadel-iterate        # Execute ONE task through full cycle:
                        #   1. PREFLIGHT (env + INVEST check)
                        #   2. MCP VALIDATE (tech patterns)
                        #   3. RED (failing tests)
                        #   4. GREEN (minimal impl)
                        #   5. REFACTOR (quality)
                        #   6. VERIFY (gates)
                        #   7. RETROSPECTIVE (learnings)
                        #   8. COMPLETE (state update)

Continuous Implementation

Loop:
  /citadel-iterate      # Full iteration cycle
  Review retrospective
  Continue until phase complete

At phase boundary:
  Validate PHASE-GATES.md checklist
  Proceed to next phase

Iteration Cycle Diagram

┌─────────────────────────────────────────────────────────────────┐
│                    CITADEL ITERATION CYCLE                      │
├─────────────────────────────────────────────────────────────────┤
│  1. PREFLIGHT       → Verify environment + dependencies        │
│  2. LOAD STATE      → Resume or advance to next task           │
│  3. VALIDATE DEPS   → Check dependency chain                   │
│  4. LOAD CONTEXT    → Progressive context by complexity        │
│  4.5 SPEC ENHANCE   → EARS, INVEST, ADR fitness, Gherkin (NEW)│
│  5. MCP VALIDATE    → Check tech assumptions against docs      │
│  6. RED             → Write failing tests from AC              │
│  7. GREEN           → Minimal implementation to pass           │
│  7.5 REFACTOR       → Improve quality, maintain green          │
│  7.2 ADR COMPLIANCE → Run fitness functions (BLOCKING)    (NEW)│
│  8. UPDATE STATE    → Mark complete, advance queue             │
│  9. RETROSPECTIVE   → Capture what worked, what didn't         │
└─────────────────────────────────────────────────────────────────┘

Command Relationships

┌────────────────────┐
│  /citadel-session  │  ← Start here
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐     ┌────────────────────┐
│  /citadel-status   │ ◄──►│  /citadel-audit    │
└─────────┬──────────┘     │  --ears --gherkin  │
          │                │  --adr --drift     │
          │                └────────────────────┘
          ▼
┌────────────────────┐
│ /citadel-spec-check│  ← Preview spec issues (optional)
└─────────┬──────────┘
          │
          ▼
┌────────────────────────────────────────────────┐
│              /citadel-iterate                  │
│   (Full TDD cycle with spec enhancement)       │
│   Phase 4.5: EARS, INVEST, Gherkin, ADR gen   │
│   Phase 7.2: ADR compliance (BLOCKING)         │
└────────────────────────────────────────────────┘
          │
          ▼
┌────────────────────┐
│  /citadel-next     │  ← Direct execution (same phases)
└────────────────────┘

Failure Recovery Protocol

When ANY phase fails, execution HALTS immediately.

⛔ Iteration Failed
Present recovery options:
1. Retry [--retry]       → Re-run failed phase
2. Rollback [--rollback] → Revert to pre-task state
3. Fix & Resume          → User fixes, then --resume
4. Skip [--skip]         → Mark blocked, move on
5. Escalate [--escalate] → Flag for human review

> User MUST choose - no auto-retry

All recovery actions logged to rollback_history[] in state.json.

Phase Gates

See .work/03-implementation/PHASE-GATES.md for explicit transition checklists.

Each phase gate validates:

• All tasks in phase complete
• Verification commands pass
• Quality criteria met
• Manual approval confirmed

State Management

All progress tracked in .work/state.json (schema v2.1):

• Current phase, epic, task
• Current iteration cycle state
• INVEST scores
• Completed tasks
• Blocked tasks
• Rollback history
• Iteration history with retrospectives

Priority System

/citadel-work selects work based on priority:

1. CRITICAL audit findings → Fix immediately
2. HIGH audit findings → Fix before implementation
3. Next implementation task → Execute via /citadel-iterate
4. MEDIUM audit findings → Fix between tasks
5. LOW audit findings → Optional cleanup

MCP Validation Protocol

Tasks with mcp_required: true require dual-validation:

1. Query microsoft-learn for official documentation
2. Query perplexity to validate currency (ALWAYS - microsoft-learn can be stale)
3. Query context7/ref for library-specific patterns
4. Compare with task code examples
5. Flag and resolve discrepancies before coding

TDD Execution Pattern

Every task follows RED → GREEN → REFACTOR:

1. RED: Write failing tests from acceptance criteria
2. GREEN: Implement minimum code to pass (no extras)
3. REFACTOR: Improve quality, maintain passing tests

Quality Gates by Complexity

Complexity	Hours	Requirements
S (Simple)	0.5-2h	Build passes
M (Medium)	2-8h	+ 60% coverage
C (Complex)	8-24h	+ 80% coverage + arch tests
VC (Very Complex)	24-40h	+ Human review flag

Integration with .work Folder

.work/
├── ACTIVE.md              # Current focus
├── state.json             # Machine-readable state (v2.1)
├── 01-requirements/       # Requirements with EARS patterns + INVEST scores
│   └── acceptance/        # Gherkin feature files (NEW)
├── 02-architecture/       # Architecture decisions
│   └── decisions/         # ADRs with fitness_functions metadata (NEW)
├── 03-implementation/     # Phase/Epic/Task hierarchy
│   ├── PHASE-GATES.md     # Transition checklists
│   ├── phase-*/
│   │   └── EPIC-*/
│   │       └── TSK-*.md   # Tasks with spec refs + gherkin_scenarios
├── schemas/
│   ├── task.schema.json         # Task YAML validation
│   ├── state.schema.json        # State validation
│   ├── ears-requirement.schema.json  # EARS pattern validation (NEW)
│   ├── adr-fitness.schema.json  # ADR fitness functions (NEW)
│   └── invest-scoring.md        # Scoring rubric
├── scripts/               # Automation scripts
│   ├── Add-InvestScore.ps1
│   ├── Test-InvestScore.ps1
│   ├── Test-EarsCompliance.ps1      # EARS validation (NEW)
│   ├── Test-GherkinSyntax.ps1       # Gherkin validation (NEW)
│   ├── Test-AdrCompliance.ps1       # ADR fitness functions (NEW)
│   ├── Test-SpecificationDrift.ps1  # Drift detection (NEW)
│   ├── New-ReqnrollFeatures.ps1     # Feature file generator (NEW)
│   └── ...
└── audit-results/         # Validation output
    ├── ears-compliance.json         # (NEW)
    ├── gherkin-validation.json      # (NEW)
    ├── adr-compliance.json          # (NEW)
    └── drift-report.json            # (NEW)

Best Practices

1. Always start with /citadel-session - loads context and verifies environment
2. Run /citadel-audit before implementation - ensures .work folder integrity
3. Use /citadel-spec-check to preview issues - optional but recommended
4. Use /citadel-iterate for primary workflow - full TDD cycle with retrospective
5. Check INVEST score before starting - must be >= 7/12
6. Let Phase 4.5 enhance specs - EARS patterns and ADR fitness auto-generate
7. Never skip MCP validation - prevents stale patterns in code
8. ADR violations block task completion - fix architecture before proceeding
9. On failure, choose recovery action - no silent auto-retry
10. Capture retrospectives - enables cross-task learning
11. Validate phase gates before transition - explicit checklists

Error Recovery Quick Reference

Situation	Action
Task fails verification	Present options, wait for user choice
Task blocked by dependency	Show chain, offer to execute blocker
INVEST score < 7	Remediate task before implementation
MCP discrepancy	Flag and confirm before proceeding
ADR violation detected	Fix architecture, cannot bypass
Missing EARS pattern	Auto-generated in Phase 4.5
Missing ADR fitness function	Auto-generated in Phase 4.5
Specification drift detected	Logged, may require manual review
Phase gate fails	Fix criteria before advancing
Context window full	Run /compact, resume iteration