Spec-Kit and Context-V Coexistence

Why this blueprint exists

On 2026-05-18, augment-it adopted github/spec-kit (v0.8.11) as its implementation workflow framework. Spec-kit is a structured Spec-Driven Development toolkit from GitHub: AI generates a spec, then a plan, then tasks, then code — with explicit human gates between phases. Augment-it is the first Lossless project to use it.

The team’s existing convention is context-v — the six-folder living-documentation system (specs / prompts / blueprints / reminders / explorations / issues) plus the sitemap/ and plans/ extensions. Context-v is broader than spec-kit; it holds project memory across the full lifecycle, not just implementation flow.

These two systems overlap and could conflict if used naively. This doc captures how to use them together so neither gets confused, drifts, or ends up partially adopted.

What spec-kit installed in augment-it

Two surfaces:

.claude/skills/ — 14 new slash commands

.specify/ directory

.specify/
├── extensions/git/        # Git workflow extension
├── extensions.yml         # Extension config
├── init-options.json
├── integration.json
├── integrations/          # Per-AI-agent integration metadata
├── memory/                # Spec-kit's persistent state (separate from context-v)
├── scripts/bash/          # Automation scripts
├── templates/             # Spec, plan, tasks templates
└── workflows/speckit/     # workflow.yml — the phase-gate definition
    └── workflow.yml

How they coexist — the boundaries

The rule of thumb:

• “What are we building, and why?” → context-v
• “How do we implement this specific feature, step by step?” → spec-kit

The workflow we adopt

For augment-it’s walking skeleton onward, the flow becomes:

1. Context-v captures intent. Specs like Augment-It-as-CRM-Augmentation-Pipeline.md and Walking-Skeleton-Pre-Flight-Decisions.md already exist. New exploratory thinking continues to land in context-v.
2. /speckit-constitution establishes project principles. Recommended seed content: point the constitution at the existing context-v blueprints — Per-App-Workspace-Conventions, Why-Response-Reviewer-and-Highlight-Collector-Exist, Module-Federation-Rsbuild-Dev-Loop-Gotchas, Spec-Kit-and-Context-V-Coexistence (this doc). The constitution becomes the load-bearing reference for spec-kit’s other phases.
3. /speckit-specify generates a feature-level spec under .specify/memory/specs/. Feed it the relevant context-v docs as background.
4. /speckit-clarify (optional) de-risks ambiguous areas. Useful for first-of-kind work like the in-app-agent scaffolding.
5. /speckit-plan generates implementation plan.
6. /speckit-checklist (optional) generates quality gates.
7. /speckit-tasks generates the actionable task list.
8. /speckit-analyze (optional) cross-checks consistency.
9. Human review gate. Per workflow.yml, each major phase has an approve | reject gate. We honor it.
10. /speckit-implement executes — writes the code per the tasks.

What does NOT change

• All existing context-v docs remain authoritative. [[Augment-It-Prior-Art-Survey]], [[Federation-and-Bundler-Decision]], [[Per-App-Workspace-Conventions]], [[Remote-Mount-Contract-for-In-App-Agent]], [[Multi-Agent-Research-Fan-Out-Per-Row]], [[Why-Response-Reviewer-and-Highlight-Collector-Exist]], [[Module-Federation-Rsbuild-Dev-Loop-Gotchas]], [[Walking-Skeleton-Pre-Flight-Decisions]] — all still load-bearing.
• Decisions in context-v override spec-kit defaults. If a /speckit-plan suggests using Zustand and our pre-flight decisions say hand-rolled useSyncExternalStore, the pre-flight decision wins. The constitution should make this explicit.
• Six-folder context-v convention. Stays as the team-wide pattern across all repos.
• Status discipline. Spec-kit’s phases (constitution → specify → plan → tasks → implement) live inside .specify/; context-v’s status: field discipline applies to context-v docs only.

What this enables

• Disciplined feature work. Each new feature in augment-it goes through specify → plan → tasks → implement with gates. No more “AI just wrote a bunch of code and we’re not sure if it matches what we said.”
• Reusable conventions. The /speckit-* skills are now available in any Claude Code session opened in augment-it. They’re not project-specific; they’re toolkit.
• A real test of the workflow. Per the user’s “I need experience implementing other people’s systems to understand how to think about our own,” using spec-kit on augment-it is the experiment. We will learn what works, what doesn’t, and what context-v might want to borrow.

What we’re watching for

Honest unknowns as we adopt this:

1. Will spec-kit’s specs conflict with context-v specs? They live in different directories (.specify/memory/ vs. context-v/specs/), so no path collisions, but conceptual confusion is possible. The boundary rule above is the discipline.
2. How much does the constitution need to encode? First pass: cite the existing context-v blueprints. Iterate as we learn what spec-kit needs to know that isn’t in the blueprints.
3. Will the gates feel like ceremony or like discipline? Approve/reject gates between phases are the right shape in principle. Real test: do they slow us down or catch real issues?
4. What happens when context-v thinking changes mid-feature? If a /speckit-plan has been approved and a context-v exploration revises the architecture, the plan should be re-generated. We trust the docs over the static plan.
5. Cross-app applicability. If augment-it’s adoption goes well, memopop and dididecks may adopt too. The constitution’s per-project flavor is the variable; the toolkit is shared.

Anti-patterns to avoid

• Putting living docs in .specify/memory/. That’s spec-kit’s per-feature scratch space. Project memory belongs in context-v/.
• Putting per-feature task lists in context-v/. That’s spec-kit’s job. Context-v plans are slide content, multi-session plans, and broader feature framings.
• Skipping the gates. The approve/reject gates exist for a reason. Treating them as paperwork undermines the whole spec-driven model.
• Ignoring context-v when running spec-kit. Spec-kit needs the context — feed it relevant context-v docs at each phase, especially /speckit-specify and /speckit-plan. Without context-v as input, spec-kit re-derives architecture from training data, which is worse than what we already have.
• Treating spec-kit’s constitution as a one-shot. Constitutions evolve. Re-run /speckit-constitution periodically as patterns harden.

Reading order for someone new

If you’re loading augment-it cold and want to understand how to work in it:

1. augment-it/context-v/explorations/Augment-It-Prior-Art-Survey.md — what augment-it is, what was tried before
2. augment-it/context-v/specs/Walking-Skeleton-Pre-Flight-Decisions.md — the five concrete substrate calls
3. This blueprint — the workflow framework
4. .specify/memory/constitution.md (once generated) — the principles spec-kit will respect
5. Any active /speckit-* outputs in .specify/memory/ — the current feature in flight

Related

• [[Walking-Skeleton-Pre-Flight-Decisions]] — the five substrate decisions
• [[Augment-It-Prior-Art-Survey]] — project context
• [[Per-App-Workspace-Conventions]] (ai-labs) — the workspace pattern
• [[Federation-and-Bundler-Decision]] — the federation stack
• [[Multi-Agent-Research-Fan-Out-Per-Row]] — the runtime concerns
• studies/open-specs-and-standards/spec-kit/ — upstream code and docs (study submodule)
• studies/open-specs-and-standards/spec-kit/AGENTS.md — how integration classes work
• https://github.com/github/spec-kit — upstream
• https://github.github.io/spec-kit/ — official docs