1. If My Manual Workflow Was Working, Why Change It?

When developers consider adopting GitHub Spec Kit, the conversation usually focuses on installation, commands, and how to structure specifications. But for those already practicing spec-driven development, there's a more interesting question: If you've built a manual workflow that works well, what do you actually gain by moving to a standardized framework?

This was the question I faced when I decided to migrate one of my existing projects to GitHub Spec Kit. I had already developed my own spec-driven development processes after learning the approach through DeepLearning.AI. Those workflows worked well, and I still use manual processes in two projects without any fundamental problems. I wasn't trying to fix something broken.

What changed was my perspective on long-term maintenance. A workflow that works for its creator isn't necessarily the easiest for new contributors to learn, different coding agents to execute, or multiple projects to share. I began to see potential benefits in standardization, particularly for onboarding, agent portability, consistency, and community-maintained improvements.

However, migrating an existing project introduces complications that don't exist when starting from scratch. In my case, the main challenges involved reorganizing existing documentation, replacing manual agent instructions, and preserving historical specifications. These challenges eventually shaped a reusable migration playbook, which I'll also explain so that others can follow the same approach.

2. How I Started with Spec-Driven Development

My introduction to spec-driven development came through DeepLearning.AI's Spec-Driven Development with Coding Agents course, taught by Paul Everitt in collaboration with JetBrains. The course introduces a structured approach to AI-assisted development: establish project principles, define requirements, plan implementation, execute changes, and validate the results.

One aspect I particularly appreciated was that these principles didn't require a specific framework. Developers could create their own workflows and package them into reusable agent skills. That's exactly what I did.

I built manual processes tailored to my projects, defining how specifications, project instructions, implementation plans, tasks, and validation should work together. This gave me control over the process. I could decide which stages were necessary, how documentation should be organized, and how much structure each project required. More importantly, it worked.

That experience shaped how I evaluated Spec Kit. The comparison wasn't between an unstructured approach and a disciplined one. It was between two ways of implementing spec-driven development: a custom workflow maintained locally and a standardized workflow supported by a broader community.

3. Why Spec-Driven Development Matters

AI coding agents can generate working software quickly, but their effectiveness depends partly on how clearly developers communicate their intentions. Consider a common scenario. You ask an agent to implement a feature, review the result, and discover a missing edge case. After another prompt, the agent addresses it but unintentionally changes previously established behavior. You provide more context, and the cycle continues.

The problem isn't necessarily the agent's ability to write code. It's that requirements, assumptions, and decisions remain scattered across conversations rather than captured in a stable, reviewable form. Spec-driven development addresses this by making specifications central to the development process.

Instead of immediately implementing a request, the workflow establishes expected behavior, resolves ambiguity, plans technical changes, organizes tasks, and validates the implementation against explicit requirements.

This offers several advantages:

• Clearer requirements: Important assumptions and ambiguities can be addressed before implementation.
• Persistent context: Specifications and decisions remain available across sessions and coding agents.
• Better planning: Expected behavior is separated from technical implementation decisions.
• Greater traceability: Developers can connect requirements with plans, tasks, and results.
• More meaningful verification: Completion can be assessed against explicit criteria instead of relying solely on an agent's claims.

Of course, specifications can be incomplete, plans can be flawed, and tests can miss important behavior. A structured process doesn't guarantee correctness. Its value lies in creating opportunities to discover problems earlier and evaluate results more systematically.

Crucially, these benefits come from spec-driven development itself, not from GitHub Spec Kit specifically. A well-designed manual workflow can provide them too. So why adopt a framework?

4. Why I Decided to Adopt GitHub Spec Kit

My motivation wasn't to improve code generation directly. It was to reduce the organizational and maintenance costs surrounding the development workflow. As projects grow, those costs can become increasingly important.

4.1. Easier Onboarding for New Contributors

A custom workflow is usually easiest to understand for the person who created it. New contributors must learn its document structure, conventions, commands, exceptions, and implicit assumptions alongside the application's architecture.

A standardized framework provides shared conventions. Developers familiar with Spec Kit can transfer that knowledge between projects, while newcomers can rely on public documentation and examples. This doesn't eliminate project-specific onboarding. Every repository still has its own requirements and architecture. But it can reduce the amount of custom workflow knowledge contributors need to acquire.

4.2. Better Portability Between Coding Agents

The coding-agent ecosystem evolves quickly, and different tools offer different capabilities and integrations. When a workflow is tightly coupled to one agent's commands or configuration, switching tools may require redesigning parts of the process.

Spec Kit supports multiple coding-agent integrations while maintaining recognizable workflow stages and artifacts. The invocation syntax can differ. For example, Codex uses skill commands such as $speckit-specify, while other agents may use slash commands. However, the underlying responsibilities remain similar.

This doesn't guarantee identical results across agents or eliminate integration work. It can reduce the effort required to preserve the development process when changing tools. For me, that's valuable because I don't want my project's methodology to depend entirely on one coding agent.

4.3. Community-Maintained Workflows Can Be More Mature

Manual workflows naturally evolve through experience. You start with specifications and implementation steps. Eventually, you encounter ambiguous requirements and introduce clarification. Later, you notice inconsistencies between plans and specifications, so you add analysis. Then you realize completed tasks don't necessarily mean satisfied requirements, so you establish a separate verification stage.

Over time, the workflow becomes more comprehensive. This is valuable, but it also means discovering gaps, designing safeguards, and maintaining improvements yourself.

A community-maintained framework can benefit from contributors working across different projects and encountering problems an individual developer hasn't experienced. That collective experience may produce more mature conventions, reusable safeguards, and broader integration support.

Community maintenance doesn't guarantee stability or quality. Framework updates can introduce complexity or compatibility changes. Nevertheless, distributing workflow improvements across a broader ecosystem can reduce the effort required from individual teams.

4.4. Greater Consistency and Lower Maintenance Costs

When every repository uses different specification structures, skill names, planning conventions, and validation procedures, moving between projects requires additional context. Standardization reduces some of that variation.

It also encourages clearer separation of responsibilities. Project principles belong in the constitution, operational rules in agent instructions, feature requirements in specifications, and implementation decisions in plans and tasks. This can prevent important guidance from becoming scattered across overlapping or contradictory documents.

There is also a maintenance advantage. A custom process requires updating its templates, prompts, instructions, and automation. A shared framework can handle part of that evolution, allowing developers to concentrate on project-specific requirements. Maintenance doesn't disappear, however. It changes form: instead of maintaining every workflow component yourself, you maintain your project's integration with the framework.

5. When a Manual Workflow Is Still the Better Choice

There is a strong counterargument to adopting Spec Kit: a custom workflow may be simpler, more flexible, and better suited to the project. A standardized framework introduces conventions, commands, templates, dependencies, and upgrade considerations. Developers must learn those concepts and decide which stages are appropriate.

For a small project maintained by one developer, that overhead may outweigh the benefits. A manual workflow may also be preferable when requirements are specialized, the development process is intentionally lightweight, or the existing approach is already well documented and easy to maintain.

More documentation doesn't automatically mean better engineering. Generating specifications, plans, and tasks without using them meaningfully can turn a useful process into unnecessary ceremony.

The case for standardization becomes stronger when multiple contributors need a shared process, different coding agents are used, several repositories would benefit from common conventions, or maintaining custom workflow infrastructure becomes expensive. It becomes weaker when the existing process is simple, stable, and already meets those needs. That's why I don't believe every project should adopt Spec Kit automatically.

The right question isn't whether a standardized framework is universally better. It's whether its benefits outweigh the complexity it introduces in a particular project.

6. The Real Migration Challenge Wasn't Installation

Once I decided to move one project to Spec Kit, the challenge shifted from evaluating the framework to introducing it safely. I wasn't starting with an unstructured repository. The project already had documentation, agent instructions, and specifications developed through my manual process.

Those artifacts contained useful knowledge. Simply replacing them would risk losing information, while leaving everything untouched could create conflicting workflows. Three challenges became particularly important.

6.1. Reorganizing Documentation Without Losing Project Knowledge

In a manually developed workflow, documentation grows around the conventions you establish. Different files may contain project principles, architectural decisions, development instructions, feature requirements, and historical implementation details.

Those responsibilities don't necessarily map directly to Spec Kit's structure. For example, Spec Kit provides a constitution for durable project principles, but that doesn't mean every existing development guide belongs in the constitution. Architecture documentation, contributor instructions, and feature specifications have different purposes.

The challenge was therefore not simply moving Markdown files between directories. It was determining what each document was responsible for and where that responsibility should live afterward. This raises an important ownership question: if an architectural principle is transferred into the constitution, should it still appear as an active rule elsewhere?

Keeping duplicate instructions can eventually produce contradictions. Removing the original too early may lose useful context. The approach I developed was to inventory the documentation, classify its responsibilities, identify appropriate owners, and preserve originals before adapting anything.

Documentation migration should be treated as a reorganization of knowledge, not merely a reorganization of files.

6.2. Replacing Manual Agent Instructions Without Creating Conflicts

The second challenge concerned the instructions I had created for coding agents. A manual spec-driven workflow depends heavily on these instructions. They establish when the agent should create specifications, how it should plan implementation, and which checks it should perform before claiming completion.

After adopting Spec Kit, some of these responsibilities become part of the framework's commands and skills. That creates a risk of conflicting instructions. If the old workflow remains active, the agent may encounter two different descriptions of how development should proceed.

The solution isn't to delete every instruction file. Some instructions describe the manual workflow and may become redundant. Others contain project-specific requirements that remain essential regardless of the framework.

Architectural boundaries, testing expectations, compatibility constraints, and repository conventions should not disappear simply because the development process changes. I therefore approached the migration by separating workflow instructions from durable project guidance.

Obsolete instructions should be retired only after their useful content has been preserved and their replacement responsibilities are clear. Replacing a development workflow should not mean replacing the project's engineering principles.

6.3. Preserving Historical Specifications Without Treating Them as Current Requirements

The third challenge involved historical specifications. Because the project had already used a manual spec-driven process, those documents were valuable. They recorded earlier requirements, decisions, and intended behavior.

But historical specifications introduce a complication during migration. A specification written for an earlier version of a feature doesn't necessarily describe its current implementation. Requirements may have changed, features may have evolved, and some intended behavior may never have been implemented.

Automatically converting every historical specification into a current Spec Kit specification could therefore create misleading documentation. Discarding them, however, would lose useful project history.

The approach I developed separates historical intent from current implementation and validation evidence. Historical specifications remain available as reference material, while current capabilities can be documented using evidence from source code and tests. Formal baseline specifications can then be created selectively when they provide value.

There is no need to reconstruct the entire application's development history or invent completed Spec Kit workflows for features built before the migration. Historical specifications should help explain where a project came from, not automatically define where it stands today.

These three challenges shaped the migration method that follows.

7. A Reproducible Migration Process for Existing Repositories

The approach below is adapted from my migration playbook. It is intended as a reusable procedure, not a claim that every repository will encounter the same problems or require identical changes. The playbook includes copyable prompts, preservation procedures, completion checks, recovery guidance, and instructions for resuming work in another chat.

The examples use Codex Desktop on Windows with PowerShell and Spec Kit command conventions checked against version 1.2.1. Other coding agents and releases may require different installation options or invocation syntax. The most important rule is to execute one stage at a time, review its output, and proceed only when its prerequisites are satisfied.

How to Execute the Prompts Across Coding-Agent Sessions

The prompts in this guide are designed to form one continuous migration, not a collection of independent tasks.

The simplest approach is to use the same coding-agent conversation throughout the migration. First provide the repository context in Section 7.2, then execute A1, review the result, execute A2, and continue in sequence. Each new prompt builds on the context and artifacts established by earlier stages. Do not paste all prompts at once or allow the agent to advance automatically.

You can also continue in a new conversation, which may be useful if a session becomes too long or you want to resume later. However, a new conversation should not be assumed to remember earlier instructions, approvals, selected specifications, or migration decisions.

In that case, provide the repository context again, identify the exact stage where you stopped, and instruct the agent to recover the state from the files and records produced during the earlier stages. Verify that it selects the correct specification directory before allowing new changes.

This distinction matters because the repository artifacts and migration records should be the source of truth, not the coding agent's conversation history. Even when using the same session, review the actual outputs before advancing.

Section 7.2 includes a reusable prompt for restarting in a new conversation.

7.1. First, Choose Your Migration Scope

Not every repository needs a full migration.

If you only want to start using Spec Kit for future changes, installation and project guardrails may be sufficient. If you have an established manual specification workflow, the documentation migration is more relevant. Baseline specifications for existing features are optional.

GitHub's official existing-project guidance also supports incremental adoption rather than recreating an entire application from specifications.

7.2. Establish the Repository Context

Before the migration, open the intended repository in your coding agent. Provide its path, the selected scope, the environment, and the rules that should govern the work.

For example:

Repository: <REPO_ABSOLUTE_PATH>
Migration scope: guidance and capability catalog
Coding agent: Codex Desktop
Integration: codex
Operating system: Windows
Shell: PowerShell
Script type: ps
Archive: <REPO_ABSOLUTE_PATH>/migration-input/

Migration rules:
- Preserve application behavior, source, tests,
  runtime configuration, and existing CI.
- Preserve useful documentation and custom skills.
- Treat historical documents as reference material,
  not current agent instructions.
- Do not overwrite existing files without review.
- Request approval before installing dependencies.
- Do not commit, push, or publish.
- Report actual changes and validation results.
- Execute only the requested migration stage.

Replace the repository path with an actual absolute path and adjust the environment to match your setup. This initial context is important because a coding agent shouldn't infer that adopting a new framework authorizes unrelated repository changes.

For a new migration: Send this context once at the beginning of the coding-agent conversation. Then send the A1 prompt from Section 7.3 in that same conversation. Continue with subsequent prompts only after reviewing the previous stage.

For a migration resumed in a new conversation: Reestablish the same context, then use the following handoff prompt rather than restarting the migration from A1.

Continue the existing GitHub Spec Kit migration
in <REPO_ABSOLUTE_PATH>.

Migration scope: <SELECTED_SCOPE>
Current stage: <STAGE_ID>
Selected specification directory: <ABSOLUTE_SPEC_DIRECTORY>
Archive location: <ARCHIVE_PATH>
Checkpoint reference: <CHECKPOINT_ID_OR_BACKUP_PATH>

Read the current repository instructions, constitution,
migration records, selected specification, and existing
validation evidence.

Recover the decisions, completed stages, and unresolved
findings from those artifacts.

Verify the installed Spec Kit integration and confirm
that the selected specification directory is correct.

Do not repeat completed installation, checkpoint,
archive, or specification-creation stages.

Preserve existing work and report the recovered state
before proceeding.

Execute only the requested stage.

Replace the placeholders with values recorded during the earlier session. Omit or mark not applicable any artifacts that don't yet exist, such as a specification directory before the specification stage.

The agent should first verify the recovered state. If important context is missing or contradictory, resolve that before continuing.

Continue when: the repository, environment, selected scope, preservation constraints, and current stage are explicit.

7.3. Stage A1: Inspect the Existing Repository

The first operational step should be read-only. Ask the agent to inspect the current documentation and workflow before installing or modifying anything.

A simplified version of the inspection prompt is:

Inspect this repository for migration to GitHub Spec Kit.
Keep this stage read-only.

Inventory existing documentation, specifications,
agent instructions, custom skills, and workflow automation.

Identify architecture guidance, development conventions,
testing requirements, and current project principles.

Map each responsibility of the old workflow to:
1. A Spec Kit responsibility
2. Retained project documentation
3. A useful custom skill
4. A proposed retirement

Inspect Git status, branch, HEAD, existing Spec Kit
installation, dependencies, and potential file collisions.

Report the inventory, migration map, preservation plan,
conflicts, and proposed next actions.

Do not install, move, modify, or delete anything.

The important result is a responsibility map, not a long list of filenames. For example, project principles may belong in the constitution, architecture guidance may remain in ordinary documentation, and agent-specific workflow machinery may be replaced by Spec Kit skills.

These are classification options, not instructions to move every document automatically.

Expected output: a repository inventory, a proposed document-responsibility map, an installation assessment, and a checkpoint plan.

Continue when: every important category of existing documentation has been considered, and no destructive action has been taken.

7.4. Stage A2: Create a Checkpoint and Preserve Historical Material

Once the repository has been inspected, establish a recoverable baseline. Git history is useful, but it doesn't necessarily preserve all current work. Staged changes, unstaged modifications, untracked files, ignored files, and submodule changes may require different handling.

My playbook uses a retained checkpoint stash where appropriate, supplemented by separate verified backups for material the stash doesn't cover. It also creates an inactive archive containing copies of useful documentation and relevant historical specifications.

A prompt for this stage is:

Create the migration checkpoint and reference archive
using the approved repository inventory.

Record Git HEAD, branch, staged and unstaged changes,
untracked files, and existing stash identifiers.

Where applicable, create a distinctly named checkpoint
stash, record its exact object ID, restore the captured
working state, and retain the stash.

Preserve relevant files not covered by the stash
through a separate verified backup.

Copy useful documentation and historical specifications
into an inactive archive without deleting live originals.

Preserve relative paths and historical provenance.
Create a manifest with byte counts and SHA-256 checksums.

Verify archive integrity and report any limitations.

Do not modify application files or unrelated work.

For historical agent instructions, an important precaution is to prevent archived files from being treated as live instructions. For example, archived AGENTS.md and SKILL.md files can be stored as inactive .md.txt snapshots.

Also remember that git stash apply retains the stash, while git stash pop may remove it. A checkpoint stash preserves the pre-migration state, but it isn't a complete rollback procedure for changes made afterward.

Expected output: a recorded checkpoint, verified documentation archive, provenance manifest, and a report of anything not covered.

Continue when: the original state can be recovered and relevant historical material has been preserved.

7.5. Stage A3: Install Spec Kit Safely

With the original state protected, the next step is installing or verifying the intended Spec Kit integration. Before initialization, inspect any existing installation and compare the files Spec Kit proposes to create with the repository's current contents.

For the Windows/Codex configuration, useful inspection commands are:

specify version --json
specify init --help
specify integration status --json

If required tooling is missing, identify the dependency, its version, and installation location before installing it.

After reviewing potential file collisions, the initialization command for the configuration used in my guide is:

specify init --here --integration codex --script ps --ignore-agent-tools

The codex integration targets Codex, ps selects PowerShell scripts, and --ignore-agent-tools skips checks for a separate agent CLI executable.

Do not run this command blindly against a repository containing existing instructions at managed paths. If initialization requires forced merging in an existing directory, review the collisions first. A staging approach that introduces only reviewed files may be preferable to overwriting existing files automatically.

After initialization, verify the installed integration, scripts, skill manifests, and preservation of protected files.

Expected output: a verified Spec Kit installation with no unexplained overwrites or modifications.

Continue when: the intended skills and scripts are present, the integration is usable, and existing project material remains intact.

If you selected installation-only adoption, you can proceed directly to final acceptance.

8. Migrating Documentation Through the Spec Kit Workflow

For a repository that already has substantial manual documentation and specification processes, I recommend treating the migration itself as one explicit Spec Kit change. This allows the new framework to manage the transition using its own specification, planning, task, and verification stages.

The important boundary is that this remains a documentation-focused change, not an application refactoring effort. The following stages should continue in the same coding-agent conversation established earlier, unless you explicitly resume in a new one using the handoff procedure in Section 7.2.

8.1. Establish the Constitution

Start with $speckit-constitution. The constitution should capture durable project principles from existing instructions, architectural documentation, and explicitly agreed decisions.

It should not invent standards simply to fill a template. If the project already has a meaningful constitution, preserve and amend it rather than replacing it with generic content.

Expected output: a project-specific constitution with clear principles and any unresolved conflicts identified.

8.2. Specify the Documentation Migration

Next, use $speckit-specify to define the migration as a bounded change.

For example:

$speckit-specify Migrate this repository's useful
project guidance from the manual specification workflow
to the installed GitHub Spec Kit workflow.

Use the current constitution, repository inventory,
preserved historical documents, current source, and tests.

Produce:
- A disposition for every inventoried guide
- Adapted documentation with clear canonical owners
- Updated agent instructions and navigation
- An evidence-backed catalog of existing capabilities
- A record of migrated and retired workflow material

Preserve useful custom skills, historical evidence,
license information, and unrelated documentation.

Retire obsolete local workflow instructions only after
their useful content has been preserved and replacement
responsibilities established.

Do not change application source, tests, runtime
configuration, existing CI, or unrelated work.
Do not commit, push, or publish.

This specification defines what a successful documentation migration must deliver and what it must leave unchanged.

Expected output: a migration specification, its requirements-quality checklist, and the selected specification directory.

Record that directory's absolute path. Later commands need to operate on the correct specification rather than an arbitrary or newly created one.

8.3. Clarify Conflicts Before Planning

Use $speckit-clarify to resolve questions that cannot be answered confidently from repository evidence. For example, should an old testing rule become part of the constitution or remain in contributor documentation? Is a historical specification still authoritative? Which obsolete skills can safely be retired?

These are decisions that should be resolved before implementation, not left to the agent's assumptions.

Expected output: important ownership, scope, and acceptance decisions recorded in the specification.

8.4. Plan the Documentation Reorganization

Use $speckit-plan to generate the migration plan and perform repository research. The plan should account for every inventoried document, including its source, intended destination, treatment, and rationale.

A useful classification is:

These are conventions to adapt, not mandatory directory names.

This stage should also identify existing application capabilities by inspecting relevant source code, tests, and historical documents. Importantly, the agent should distinguish historical requirements from current implementation and actual validation evidence.

Expected output: a migration plan, per-document ownership map, capability findings, and planned validation checks.

Continue when: document ownership is clear and the capability grouping has been reviewed.

8.5. Generate and Review the Migration Tasks

Use $speckit-tasks to produce dependency-ordered work from the specification and plan. Tasks should cover adapting documents, updating links, preserving historical material, creating the capability catalog, and validating the resulting documentation.

An obsolete instruction should not be removed before its useful content has an appropriate owner. Then run $speckit-analyze to check the specification, plan, and tasks for inconsistencies, missing coverage, unsupported claims, or unauthorized application changes.

If analysis identifies material problems, return to the responsible earlier phase instead of proceeding with inconsistent artifacts.

Expected output: a complete task list and a consistency review without unresolved material findings.

8.6. Implement the Documentation Changes

Once the plan and tasks have been reviewed, use $speckit-implement. In this context, implementation means carrying out the documentation migration.

The agent should adapt useful guides, update live instructions, repair navigation, create the capability catalog, and record what changed. It should deactivate only the identified obsolete workflow instructions after confirming that their useful content has been preserved.

Application code, tests, runtime configuration, and existing CI remain outside the authorized scope.

After implementation, run $speckit-converge to assess the documentation deliverables against the specification, plan, and tasks. If convergence identifies remaining work, complete the additional tasks and repeat the assessment.

Expected output: adapted documentation, a capability catalog, migration records, validation evidence, and a convergence report.

Continue when: the documentation work has converged or any remaining limitations have been explicitly identified.

9. What Should You Do with Features That Already Exist?

After migrating the documentation, you may wonder what to do with the features your application already has.

Suppose your project already includes user authentication, reporting, data export, and several other capabilities. These features were implemented before adopting Spec Kit, possibly using your previous manual specifications.

Do you now need to create new Spec Kit specifications for every existing feature? Not necessarily.

The distinction is between documenting what already exists and formally specifying an individual feature.

9.1. First, Create a Catalog of Existing Features

A capability catalog is simply an organized overview of what your application currently provides. It is not a new specification for every feature. Think of it as an index that helps developers and coding agents understand the existing application.

For each capability, the catalog can record:

• A stable identifier and descriptive name.
• What the feature does from the user's perspective.
• Where its implementation can be found in the source code.
• Which tests are relevant.
• Whether historical specifications exist.
• Known limitations, discrepancies, and unanswered questions.

For example, imagine an application with an existing CSV export feature.

Its catalog entry might look like this:

This is an illustrative example, not a description of my repository.

The catalog doesn't require the coding agent to implement or modify anything. It requires the agent to inspect the repository and record what the available evidence supports.

In the migration process described earlier, this research begins during $speckit-plan, while the final catalog is produced through the documentation tasks.

9.2. Keep Historical Requirements Separate from Current Behavior

Now imagine the historical specification for the CSV export feature says users should be able to choose which columns to export. However, the current implementation appears to export a predefined set of columns.

Which description should the new documentation use? It shouldn't automatically choose either one.

The old specification tells us what was intended at a particular time. The current code tells us what appears to be implemented. Existing tests show which behaviors are asserted, while fresh test execution provides evidence about observed results.

These sources answer different questions. The catalog should record the discrepancy rather than silently treating the old specification as current truth or assuming the existing implementation is necessarily correct.

This matters because an AI agent may otherwise turn outdated requirements into current obligations, or normalize an existing bug as intended behavior.

The goal is to document the evidence accurately, not to make the project's history appear more consistent than it actually is.

9.3. Create a Baseline Specification Only When You Need One

A capability catalog provides a useful overview, but it isn't necessarily detailed enough to guide a substantial future change. For important or frequently modified features, you may want a formal baseline specification.

A baseline specification describes the existing capability in more detail, using available evidence from current code, tests, and historical documentation.

For example, if you expect to extend the CSV export feature, a reviewed baseline could describe its current user-facing behavior, supported formats, relevant edge cases, compatibility constraints, and unresolved questions.

You don't need to create these baselines for every capability. Select the ones where having a more detailed specification provides practical value.

The process is straightforward:

1. Choose a capability from the reviewed catalog.
2. Use $speckit-specify to create its draft baseline specification.
3. Use $speckit-clarify to resolve important discrepancies or uncertainties.
4. Review the resulting specification and link it from the capability catalog.

For example, after selecting CAP-007, you could use:

$speckit-specify Create a baseline specification
for the existing capability CAP-007 (CSV Export).

Use the reviewed capability catalog, current source,
inspected tests, and historical specifications.

Describe existing user-facing behavior, scenarios,
edge cases, compatibility constraints, and known
limitations.

Distinguish historical intent from current
implementation, test assertions, and actual
execution evidence.

Identify conflicting information and open questions.
Do not invent requirements or validation results.

Create documentation only.
Do not modify application code or tests.

This is followed by $speckit-clarify for any consequential uncertainties the repository evidence cannot resolve.

Run these commands in the coding-agent conversation containing the current repository context. If you start a new conversation, first recover the selected migration state as described in Section 7.2.

The baseline should not automatically become an authoritative contract until you have reviewed it, particularly if historical requirements conflict with current behavior.

9.4. You Don't Need to Recreate the Application's Development History

One important point is that these are existing features. They weren't necessarily developed using Spec Kit, so there's no reason to make them appear as if they went through a complete Spec Kit development cycle.

Don't generate fictional completed implementation plans, tasks, test results, or approval records.

A baseline specification is a description of an existing capability, not proof that it was originally developed through that process.

For features you aren't planning to change, the capability catalog may be sufficient. When you eventually request a real behavior change, you can create or update the relevant specification and proceed through the normal clarification, planning, task generation, analysis, implementation, and convergence stages.

This keeps the migration focused on establishing a better development process rather than retrospectively documenting every implementation decision.

In short:

The capability catalog tells you what exists. An optional baseline specification documents a selected existing feature in more detail. The normal Spec Kit workflow then governs future changes.

10. Verify Completion and Preserve the Ability to Recover

A migration isn't complete simply because every command has been executed. The final acceptance review needs to establish that the selected scope has been satisfied and that existing project material remains protected.

My playbook recommends a read-only acceptance check covering:

1. Correct installation, integration, scripts, and managed-file integrity.
2. Appropriate ownership and preservation of existing documentation.
3. A substantive constitution and updated active agent instructions.
4. An evidence-backed capability catalog.
5. Reviewed baseline specifications, if selected.
6. Working documentation links and accurate historical provenance.
7. Verified archive integrity, checkpoints, and protected-file comparisons.
8. Actual validation results, skipped checks, unresolved findings, and accepted deferrals.

A useful final prompt is:

Perform a read-only acceptance review of the selected
GitHub Spec Kit migration scope.

Verify the integration, documentation ownership,
capability catalog, historical preservation,
agent instructions, archive integrity, and Git state.

Compare protected application files against the actual
pre-migration baseline, including relevant tracked
and untracked changes.

Check applicable documentation validation and report
any broader tests that were not executed.

Provide a pass/fail/not-applicable report containing
commands, outputs, artifact paths, limitations,
and unresolved findings.

State whether the selected migration scope is complete.

Do not modify files, commits, snapshots, or backups.

This distinction between completed work and verified work is particularly important in AI-assisted development. An existing test file doesn't prove that a test passed, and an agent reporting success doesn't prove that every requirement has been satisfied.

If verification fails, return to the stage responsible for the finding, correct only the authorized work, and repeat the relevant checks.

10.1. Recovering or Resuming Safely

The migration should also remain recoverable. If something goes wrong, inspect the recorded checkpoint, current working state, archive manifest, and migration changes before proposing a restoration.

Don't blindly run git reset, clean untracked files, drop stashes, or restore the old state over changes made since the checkpoint.

Recovery should identify the exact files and tools affected, preserve newer unrelated work, and require approval before destructive changes.

Similarly, if you continue the migration in another chat, don't rely on the agent remembering previous decisions. Record the current stage, selected specification directory, checkpoint identifiers, archive location, validation evidence, and unresolved questions in a migration record or handoff note.

The next session should verify that state rather than automatically repeating installation, archive creation, or specification generation. These details are covered in the companion migration playbook, which provides the complete prompts for each stage.

11. What This Experience Changed in My Thinking

Building my own spec-driven workflow was valuable because it forced me to understand the process rather than simply follow predefined commands. I learned why project principles matter, how specifications reduce ambiguity, why planning should precede implementation, and why verification must remain independent of an agent's completion claims.

That knowledge made evaluating Spec Kit easier. I could distinguish the benefits I already had from those standardization might add.

The migration also clarified something important: adopting a standardized workflow is not mainly about replacing commands. It's about deciding how existing knowledge, development rules, and historical evidence should be organized under a new process.

For a new repository, many of those decisions can be made at the beginning. For an established repository, they require understanding what already exists and why it exists.

This is also why I consider preservation central to the process. The value accumulated through a manual workflow doesn't disappear because a standardized alternative becomes available.

A successful migration should replace obsolete workflow machinery while retaining the project's engineering principles, useful documentation, and trustworthy history.

It also changed how I think about maintenance. Creating a custom process can be relatively straightforward, especially with AI assistance. Maintaining it across multiple projects, contributors, coding agents, and evolving requirements can become more demanding.

A standardized framework may reduce some of that cost, but it also creates responsibilities involving upgrades, integrations, and framework-specific conventions.

The decision is therefore not between maintenance and no maintenance. It's between maintaining a fully customized process yourself and maintaining your project's relationship with a shared framework. Which approach makes more sense depends on the project's complexity, collaboration needs, and expected evolution.

12. Conclusion: Standardize When It Reduces More Complexity Than It Introduces

My decision to migrate one project to GitHub Spec Kit wasn't driven by dissatisfaction with manual spec-driven development. The manual approach worked, and it remains appropriate for projects that benefit from a customized, lightweight process.

What attracted me to Spec Kit was the potential to reduce the organizational cost of maintaining that process: making onboarding easier, improving portability across coding agents, increasing consistency between repositories, and benefiting from community-maintained improvements.

Those advantages are meaningful, but they aren't automatic. They depend on the project's needs and the quality of the adoption process.

The migration itself reinforced another lesson: improving a development workflow shouldn't require discarding existing project knowledge. Documentation, specifications, architectural decisions, custom skills, and historical evidence are valuable regardless of the framework used to organize them.

For me, the central distinction is this:

Spec-driven development makes software requirements and implementation more deliberate. Standardization makes that development process easier to share, transfer, and maintain.

A project may benefit from the first without needing the second.

The better question isn't whether every developer should adopt GitHub Spec Kit. It's whether a project's workflow has become something that would benefit from shared conventions rather than continued project-specific maintenance.

And when the answer is yes, the transition should preserve what already works.

13. References and Further Reading

• Spec-Driven Development with Coding Agents, DeepLearning.AI
• GitHub Spec Kit, Official Repository
• Adopting Spec Kit in an Existing Project
• Spec Kit Installation Guide
• Spec Kit Command Reference
• Evolving Specifications