dasha-ws/ai-dev-framework/tech-spec

tech-spec

Purpose

/tech-spec creates, or substantially updates, the Technical Specification for one implementation work item of a target project. The artifact is:

.claude/work/<work-item-name>/tech-spec.md

A Tech Spec answers one question: how exactly should this approved work be implemented in this project? It turns reviewed requirements, the applicable agreed architecture and the current project constraints and facts into a technical design concrete enough that /build-feature does not have to redesign the work.

It does not decide again what the product or the feature must do or what the scope is. It takes no substantive architecture decision (that is /architecture), writes no production code and does not review itself. A Tech Spec is not reviewed or approved just because it was written: /review-spec is the mandatory gate after every creation or substantive update, and a PASS belongs only to the version that was reviewed.

When to use

Both scenarios take exactly one implementation work item per run, where the work needs technical design first: a substantial feature, several related code changes, an API, data model or integration change, significant workflow logic, a migration, a change across several modules, technical work with significant failure, security or data implications, or the initial implementation of a new product.

• Initial product implementation (a new product). The upstream is the current Product Spec. A separate Feature Spec is not required and must not be created artificially.
• Feature implementation (an existing product). The upstream is the Feature Spec of the work item.

Both need the prerequisites of step 4. The Tech Spec lives in .claude/work/<work-item-name>/.

When not to use

• The current directory is the ai-dev-framework repository itself. It is the source of the framework, not a target. If the root contains the framework's own skills/ folder, stop and ask which project the user means.
• The framework structure created by /init-project is missing. Stop, say what is missing and suggest /init-project (step 1).
• The work is a real microchange. A separate Tech Spec would be decoration (step 2).
• A substantial feature has no Feature Spec, or its requirements have not passed /review-spec: /new-feature-spec and /review-spec first. A Tech Spec never replaces requirements.
• The requirements themselves have to change: /product-spec or /new-feature-spec, then a mandatory /review-spec.
• The design needs a substantive architecture decision that is not agreed yet, or architecture.md is too empty to design against: /architecture.
• The user wants code, tests, a migration run, dependencies installed, infrastructure changed or a deployment.

Inputs

• Target project root. Default: the current working directory. Confirm it if there is any doubt.
• The user: the description of the work, the implementation scope where it is open, and answers to clarifying questions.
• The project itself: codebase, configuration, existing documentation and infrastructure.
• The framework structure in the target project, created by /init-project: root CLAUDE.md, .claude/skills/project-context/SKILL.md, in .claude/skills/project-context/context/ the files product.md, architecture.md, development.md and infrastructure.md, plus .claude/product/product-spec.md and .claude/work/. All are required. ux-guide.md is used only if it exists and the router marks it as relevant.
• The reviewed upstream requirements spec: the current Product Spec for initial product implementation, the Feature Spec of the work item for feature implementation.
• Architecture context: the current architecture.md, plus the architecture prerequisite of step 4.
• The installed Tech Specification template. It lives at %USERPROFILE%\.claude\ai-dev-framework\templates\work\tech-spec.md. Do not look for another template or recreate it from memory.

Files to read

Read before writing anything. All reads are read-only.

Always: the root CLAUDE.md, the project-context router, the applicable upstream requirements spec, product.md, architecture.md, development.md, infrastructure.md, the target Tech Spec if it already exists, and the installed template. When relevant: ux-guide.md, the Product Spec, related current and completed specs, the README, API documentation and other technical documentation.

From the codebase, read only what a realistic implementation design needs: the relevant source tree and entry points, affected modules and interfaces, API and schema definitions, package and dependency files, configuration, the test structure, storage and model definitions, integration code, and relevant infrastructure and deploy configuration. No full code audit. Never read real .env files, credentials or secrets.

Execution steps

1. Confirm the target, the structure and the template

Verify that the working directory is a target project, not the framework repo, and that the required framework structure from "Inputs" exists. If any of it is missing: stop, say what is missing and suggest /init-project. Do not create the structure yourself and do not rebuild it from memory.

The installed Tech Specification template is required. If it is missing, unavailable or empty: stop and report a framework installation or template problem. Do not recreate it from memory and do not invent your own structure. If the template cannot express the design the work needs: do not improvise a section. Stop, say that the framework template needs to change, and do not change it here.

2. Decide whether a Tech Spec is needed

Not every micro-edit goes through a Tech Spec. A real microchange is a typo, a trivial text change, an obvious one-line fix, a very small isolated bugfix, or another truly microscopic change where the implementation is obvious and needs no technical decision. For it: explain why a separate Tech Spec is not needed, create no decorative spec, propose the lightweight path /build-feature → relevant testing or verification → /review-code where applicable, and launch nothing. Do not stretch a substantial feature into a microchange for the sake of speed. If the scope proves substantive, use the proper workflow.

For a substantial feature or the initial implementation of a product, continue.

3. Determine the work item

Exactly one implementation work item per run.

Feature work. Use the .claude/work/<feature-name>/ folder that holds the matching feature-spec.md. The Tech Spec is .claude/work/<feature-name>/tech-spec.md. Never create a second folder for the same feature.

Initial product implementation. There may be no Feature Spec, and none is created, not even to pick a scope. Determine one concrete implementation scope first:

• If the Product Spec and the request unambiguously define one work item, use it.
• If the Product Spec describes several independently implementable parts and the user has not said which one is implemented now: do not choose the scope yourself and do not merge the whole product or MVP into one huge Tech Spec. Show reasonable decomposition options briefly, if that helps, ask which scope to take now, and create no Tech Spec until they answer.
• Choose a concise work-item name from that scope and the project's naming convention. If it is ambiguous, propose one and wait for confirmation. Do not invent several work items unasked.

Before creating a new work item, look through .claude/work/, including .claude/work/completed/, to avoid a duplicate. If a suitable one exists, use it when the request clearly means continuing or updating it, otherwise ask. Never create a duplicate under another name, and modify nothing in .claude/work/completed/ unless the user explicitly asks.

Existing `tech-spec.md`.

• The request clearly means continuing or substantially updating it: work with it.
• The intent is unclear: ask, and never overwrite it automatically as a new document.
• It is empty, damaged, or so far from the template that continuing safely is impossible: stop and describe the problem. Do not invent an alternative structure.
• The user changed it before the run: read its current content first, do not overwrite the changes blindly and keep unrelated valid content. If the new request conflicts with what is there, show the substantive conflict and ask for a decision.

4. Check the prerequisites

Reliably established. A PASS or another result named below counts as reliably established in exactly three cases:

1. the current conversation or workflow contains it for this very version, and there has been no substantive change since;
2. the user explicitly confirms that this very version already has that result and has not changed in substance since;
3. the workflow ledger .claude/work/status.md has a row for it that powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%USERPROFILE%\.claude\ai-dev-framework\scripts\workflow-state.ps1" check reports FRESH (see templates/work/status.md): a review-spec row of the upstream spec, with its route= note after a Feature Spec, or an architecture row. The script decides freshness. A STALE or missing row is not established.

In every other case it is not established. Never infer it from a file existing, git history, commits, timestamps, naming or comments, and do not guess. If the conversation or a FRESH ledger row already establishes it, do not ask for a ritual confirmation. This skill only reads the ledger and writes none of it: no approval fields, other registry or review report files.

Reviewed requirements. A Tech Spec is not written on unreviewed requirements. Feature work needs a /review-spec PASS of the current feature-spec.md, initial product implementation one of the current product-spec.md. A substantial feature without a Feature Spec: do not write a Tech Spec instead of requirements, stop and suggest /new-feature-spec. If the upstream PASS is not established: stop and suggest /review-spec for the upstream spec first.

Architecture path. A Tech Spec always takes the current architecture.md into account. /tech-spec consumes the architecture state and does not decide it: the determination of the architecture impact belongs to /architecture. Only one question is answered here: is the architecture prerequisite resolved, so that technical design may begin? A fresh architecture-reviewer PASS is mandatory for every initial product implementation and for Case C, and not for Cases A and B.