Spec-driven planning, upstream of code

The Sith planning workflow turns a feature idea into Azure DevOps stories and per-repo task specs that an implementer can pick up cold. Most teams start AI assistance at code generation; this one starts at feature breakdown, runs the discovery and interrogation that produces the specs, and treats code implementation as the easy part of the lifecycle. The planning repo holds the registry of code repos, the conventions and patterns each one follows, and the planning artifacts: features, stories, tasks, validation plans, session retrospectives.

When to reach for it

• You want AI involvement to start at feature breakdown, not at the IDE.
• You have a feature idea (a brief, a PRD, a meeting transcript) and want to turn it into Azure DevOps PBIs and tasks that someone can pick up cold.
• You want acceptance criteria, technical specs, and per-repo task breakdowns captured before code starts.
• Your feature spans more than one repo and you’d rather plan the cross-repo coordination than discover it at PR time.

How the planning repo is organized

The workflow lives in Wholesale-Sith-Happens (the team’s planning repo). The relevant pieces:

• planning/AGENTS.md: the canonical guide every agent in the system reads. Defines the interrogation methodology, story/task templates, quality standards, and review checklists.
• planning/.agent-rules/: modular rule files loaded on-demand by domain (database, feature toggles, timer functions, C# conventions, repo discovery, validation tiers).
• planning/repos/: the multi-repo registry. repos.json is the enriched catalog with one entry per repo, repo-details/{repo}.md is the deep dive on each, repo-pipelines/{repo}.json covers deploy pipelines.
• planning/features/{id}-{name}/: one folder per feature with the feature overview, planning stories, and implementation stories.
• validation/: tier definitions (Tier 1-4), validation plan templates, and the planning-maintenance standard for changes to the planning system itself.
• .claude/agents/ and .claude/skills/: 20+ specialized agents and skills, one per phase of the lifecycle.

First-time setup is planning/repos/local-config.json (gitignored, per-machine, holds local clone paths).

The planning lifecycle

Each step has a dedicated skill or agent that owns it.

Decomposition. /sith:discover-feature takes a feature brief, PRD, or meeting transcript and produces a phased story breakdown. Runs in modes: full (guided end-to-end), analyze, discover, stories, transcript. Output is a feature overview file plus a stories folder with one file per story.

Discovery and interrogation. Each story gets pattern discovery (find 2-3 existing implementations, match them exactly), schema discovery (query sys.tables / sys.columns, never guess), and structural discovery (Roslyn MCP for type contracts and cross-project references). Knowledge gaps surface as targeted questions, not vague “what do you want?” prompts. The interrogatory loop iterates until no gaps remain.

Story + task authoring. Stories are behavioral: what changes, why, acceptance criteria phrased as user-visible behavior. Tasks are technical and self-contained: one per repo, with file paths, code references, exact property names, exact test specs. The two are split for organizational reasons but treated as one deliverable. Story-task unity is enforced: any change to a story triggers task impact assessment.

Validation planning. Each story carries validation goalposts before code is written. Tier 1 is unit and integration tests, Tier 2 is console-app system tests against deployed infrastructure, Tier 3 is structural checks, Tier 4 is operational verification. Planning-system maintenance work has its own standard.

ADO sync. /sith:ado-sync pushes stories and tasks into Azure DevOps as PBIs and child tasks (one child task per repo). Markdown formatting, tags, area path, iteration path, all handled by the sync agent with a built-in validate-and-auto-fix pass.

Implementation handoff. Once stories are in ADO, implementation runs against the spec. By design, the spec answers every question the implementer would otherwise need to ask: which file, which pattern, which test, which config, which migration. The workflow’s job ends here because the upstream work has already done the hard part.

Continuous improvement. /sith:rpiv-session captures a session retrospective at story-completion time. /sith:process-feedback analyzes those retrospectives against current rules, identifies system-level improvements, and applies approved changes. The system refines itself instead of accumulating tribal knowledge.

What it produces

A real example: Feature #182466 — Planning Repo System Maintenance and Improvements is the meta-instance of the system maintaining itself. The folder shape is the standard output of the workflow:

• feature-overview.md — capabilities, success metrics, consumer applications.
• stories/ — one file per story, each carrying its own acceptance criteria, per-repo tasks, and validation plan. The four stories under 182466 cover defining the AC standard for planning-maintenance work, formalizing build/release monitoring, integrating work streams as the default feature organization, and implementing a behavior graph.

Each story file is the source of truth that gets synced to ADO as a PBI plus child tasks. Implementation runs against the synced spec; the file in the planning repo is what the workflow keeps current.

Key commands

• /sith:discover-feature — decompose a feature into phased stories with implementation specs.
• /sith:discover-story — run full discovery and interrogation against an existing story.
• /sith:discover-and-implement — discovery followed by implementation against the resulting spec, in one invocation.
• /sith:ado-sync — sync stories and tasks to Azure DevOps.
• /sith:repo-discovery — refresh the repo catalog or enrich a specific repo.
• /sith:rpiv-session — capture a session retrospective at story-completion time.
• /sith:rpiv-roundup — collect recent retrospectives and update the tracking sheet.
• /sith:process-feedback — analyze retrospectives, propose system improvements, apply approved changes.
• /sith:review-change — review proposed changes to rules, agents, templates, or skills before they ship.
• /sith:code-review — code review for PRs (single PR or team batch).

Specialized agents

Skills delegate to a roster of purpose-built agents in .claude/agents/:

• feature-decomposition turns raw input into a story-level outline and full story specs.
• planning-discovery discovers patterns, queries schemas, hydrates story/task content.
• feature-review-coordinator runs cross-story consistency, coverage, and architecture review by dispatching to four sub-reviewers.
• story-quality-review validates format, conventions, and internal consistency on a single story.
• ado-story-sync handles ADO sync end-to-end, including the validation/auto-fix loop.
• unresolved-spec-handler resolves !!UNRESOLVED!! markers across a feature once enough sibling context exists.
• process-feedback-analysis and process-feedback-implementation drive the continuous-improvement loop.
• planning-change-reviewer reviews any proposed change to the planning system itself before it lands.

Why this lives upstream of code

The payoff is not speed in any single story. It is that work moves through the system without compounding ambiguity. Story-task unity stops the spec from drifting under the implementation. The repo catalog stops decisions from being made against a stale picture of the cross-repo landscape. Validation planning stops “we’ll figure out testing later” from becoming a debt. The continuous-improvement loop stops the same friction from showing up twice.

Code implementation is the part everyone notices. The work that makes it boring is the part everyone here cares about.