Spec-Kit Best Practices Through a TOGAF Lens: An Architect's Playbook

Most architects I talk to treat Spec-Kit as a developer productivity tool. That framing is too small. Spec-Kit is an enterprise architecture instrument — it just happens to live in a repo instead of an Archi model.

If you’ve ever tried to land TOGAF inside a team that ships every two weeks, you know the friction. The ADM is rigorous, but the artifacts feel disconnected from the code. Developers respect the architecture review board the way they respect dental appointments. Meanwhile, AI coding agents are now writing 70% of the implementation — and most of them have never read your Architecture Vision document.

Spec-Kit closes that gap. It turns architecture artifacts into executable specifications that AI agents must obey. The trick, as an architect, is mapping its primitives — constitution, specify, plan, tasks, implement — onto the TOGAF ADM phases you already own.

Here’s the playbook I use. It’s heavily inspired by the hybrid spec framework best practices, but rewritten for architects who have to defend their decisions in an ARB, not just a standup.

Why This Mapping Matters

TOGAF was designed for a world where architecture decisions cascaded down to humans who’d interpret them. AI agents don’t interpret — they execute literally. That’s both the opportunity and the risk. A well-written architecture principle becomes a constitutional article that the agent enforces on every commit. A vague one becomes silent drift across thousands of generated files.

Spec-Kit gives you the enforcement surface. TOGAF gives you the decision rigour. Used together, you get something the industry has been chasing for two decades: architecture that actually shows up in the code.

Phase Preliminary → /speckit.constitution

The Preliminary Phase of the ADM is where you define your architecture principles, governance framework, and tailored ADM itself. This is exactly what Spec-Kit’s constitution.md does for a project.

The mistake I see most often is treating the constitution as a coding style guide. It’s not. It’s where your architecture principles become non-negotiable agent behaviour. If your enterprise principle says “library-first over custom code,” that belongs in the constitution as a testable article — not as a PDF nobody reads.

Architect’s checklist:

• Every constitutional article maps to a named TOGAF principle.
• Each article includes the rationale (the “why” TOGAF demands) and implications (what the agent must do).
• Approved technology choices reference your Technology Reference Model, not just preferences.
• Governance bodies are named — who can amend the constitution, and how.

If your ARB can’t sign the constitution, the project doesn’t start.

Phase A: Architecture Vision → /speckit.specify

Phase A is about capturing what the change is and why it matters — stakeholders, value, scope, constraints. Spec-Kit’s /speckit.specify does the same thing for a feature. The discipline is identical: separate intent from implementation.

The best specifications I’ve reviewed read like a Statement of Architecture Work. They describe outcomes in measurable terms, name the stakeholders affected, and explicitly call out what’s out of scope. The worst ones describe the UI in the first paragraph — which is the spec-kit equivalent of designing the database before agreeing on the business capability.

A spec is ready when an agent and a business sponsor would both nod at it.

Phases B, C, D → /speckit.plan

Business, Data, Application, and Technology architectures all collapse into plan.md for most teams. That’s a feature, not a bug — at feature scope, you don’t need four separate documents. But you do need all four perspectives.

When I review a plan, I’m looking for:

• Business architecture: which capability does this change uplift?
• Data architecture: what entities, ownership, retention, classification?
• Application architecture: which services, contracts, and integration patterns?
• Technology architecture: which platforms, runtimes, and constraints from the enterprise standards?

If the plan only answers the fourth question, you’ve got a tech design, not an architecture. The agent will happily implement it, and you’ll happily inherit a thousand small violations of your reference architectures.

Phases E & F: Opportunities, Solutions, Migration Planning → /speckit.tasks

This is where TOGAF gets pragmatic — sequencing the work, identifying transition states, planning the migration. Spec-Kit’s /speckit.tasks is the same conversation at feature granularity.

The best practice from the source guide — keep tasks atomic, 1–4 hours each — maps directly to how mature architects sequence work packages. Each task should have a clear input, output, and acceptance criterion. If a task can’t be reviewed independently, it’s a transition architecture pretending to be a work package.

For architects, this is also where you bake in risk-based sequencing. High-risk integrations first. Reversible decisions later. The agent will execute whatever order you give it, so the order matters.

Phase G: Implementation Governance → /speckit.implement

Phase G is where most TOGAF implementations die. The architecture team hands over the SAW, the build team does whatever’s expedient, and six months later the ARB discovers the reference model was decorative.

/speckit.implement is your enforcement moment. The agent executes against the constitution, the spec, the plan, and the tasks — in that order of precedence. If you’ve done the upstream work properly, governance is continuous and automatic, not a gate at the end.

The architect’s job during implementation isn’t to review every commit. It’s to:

• Monitor adherence metrics (the source guide recommends 85%+ spec adherence as a maturity bar).
• Watch for constitutional violations the agent is forced to make — those are signals your principles are wrong, not the agent.
• Capture deviations as candidate amendments, not failures.

Phase H: Architecture Change Management → Spec evolution

Every spec, plan, and constitution is versioned in Git. That’s your change log. Every amendment is a pull request. That’s your change board. Every merge to main is an approved architecture change.

TOGAF Phase H finally has a tool that doesn’t require a separate repository, a separate process, and a separate priesthood. Use it.

Requirements Management → The Living Spec

In the ADM, Requirements Management sits in the centre because it touches every phase. Spec-Kit’s executable specifications are the same idea: the spec isn’t a document you write once, it’s the continuous source of truth that the agent re-reads on every invocation.

This is the single biggest behavioural shift for architects coming from classical TOGAF: stop writing architecture for humans to interpret. Write it for agents to execute, and humans to govern.

Common Pitfalls I See Architects Make

A few patterns to avoid, drawn from real engagements:

• Treating the constitution as optional. If it’s not signed by governance, the agent will still obey it — but you’ll have no recourse when it conflicts with enterprise standards.
• Skipping /speckit.specify because “we know what we want”. You don’t. The spec is where ambiguity gets resolved before it becomes code.
• Over-specifying the plan. The plan should constrain the agent, not write the code for it. If your plan reads like pseudocode, you’ve collapsed two phases.
• Letting tasks drift past four hours. Long tasks hide architectural decisions inside implementation. Atomic tasks force the decisions to the surface.
• No metrics on adherence. If you can’t measure how often the agent honoured the spec, you can’t govern anything.

The Architect’s New Operating Model

Spec-Kit doesn’t replace TOGAF. It operationalises it. The ADM stops being a wall poster and becomes a workflow your delivery teams actually run — because the AI agent literally cannot proceed without it.

That changes the architect’s role. You’re no longer the person who writes documents nobody reads. You’re the person who writes the constitution that governs every line of generated code. The leverage is enormous. So is the responsibility.

If you’re an architect who’s been watching AI coding agents from the sidelines, this is your entry point. Pick one feature, run it through the full Spec-Kit loop, and map each artifact back to the ADM phase it satisfies. You’ll find your architecture practice has more in common with modern delivery than you thought — it just needed the right interface.

---

Reference: Spec-Kit Best Practices, hybrid-spec-framework by GKAYED.