MostAshraf/ai-sdlc-harness

README preview

# ai-sdlc-harness · v2.1

**An AI-driven SDLC harness for Claude Code.** Drives a real engineering workflow — requirements → plan → tests → code → review → security → PR → reconcile — across one or many repos. Multi-agent, language-agnostic, discovery-driven. No application code lives here, only the agents, skills, hooks, and conventions that run them.

| Workflow | Purpose | Entry point |
|---|---|---|
| **Story Workflow** | Refine and groom stories before development | `/story-workflow <command> <work-item-id>` |
| **Dev Workflow** | Take a story from requirements to merged PR end-to-end | `/dev-workflow <work-item-id>` |

> The authoritative workflow specification — phases, ownership, status transitions, non-negotiable rules — lives in [CLAUDE.md](CLAUDE.md). This README is the guided tour. New to the harness? Start with [getting-started.md](getting-started.md) for the 10-minute install-to-first-story path.

## What's new in v2.1

| Area | Change |
|---|---|
| **Quick Mode** | New `/dev-workflow quick <id>` fast-path for trivial changes (typo fixes, one-character edits, lock-file bumps). Developer + Reviewer only — Planner and Tester are skipped per CC-05.8. Eligibility is heuristic-driven via `scripts/quick-mode-classify.py`; the tracker carries an explicit `Mode: quick` header and `Quick-Mode: true` flag so P9 metrics can segment quick-vs-full runs. `QPhaseGuard` enforces the invariants (no Planner invocation, no Tester invocation, single commit). |
| **Aggregate workflow report** | New `/dev-workflow report` utility command. Reads `ai/_metrics-log.csv` and produces a multi-story rollup with `--since`, `--format md\|json`, `--story` filters. Markdown output is a Mermaid-charted scorecard; JSON is plain rows for downstream tooling. |
| **Manifest schema for commands** | Every dev-workflow command file now ships with a sibling `<command>.manifest.yaml` declaring its prerequisites, produced artifacts, exit criteria, and gate emissions. A new manifest-schema doc + cc-check enforces parity. Consumers (the orchestrator, `workflow-status`, future automation) read manifests instead of grepping command prose. |
| **Markdown size budgets** | New `cc-check-md-budget` Convention-Check enforces per-file size caps from `agents/shared/markdown-budgets.md` (e.g. command files ≤ 400 lines, context files ≤ 200). Started in WARN mode, flipped to BLOCK in this release. `scripts/markdown-size-report.py` is the human-facing version (sorted budget-status table). Top-4 command files were surgically reduced to fit (`orchestrator-rules.md` 420 → 164; `plan-generator/SKILL.md` 830 → 337). |
| **Cost + token observability** | New Stop hook `metrics-token-collector.py` aggregates per-turn token counts into the tracker so P9 metrics can report agent-token totals per phase. `_metrics-log.csv` schema bumped to v1.1.0 with a non-destructive migration. New `cost-config.md` template carries per-model rate cards; `init-workspace` Step 6d lays it down at workspace bootstrap. |

View full repository on GitHub →