takt-sdd

Write the spec. takt reliably ships the rest.

日本語

A Spec-Driven Development (SDD) workflow definition repository using takt.

Automates the entire development flow — from requirements definition through design, task decomposition, implementation, review, and validation — using takt pieces (YAML workflows) and facets.

takt-sdd is compatible with Kiro (.kiro/specs/) and can be used alongside it.

Features

takt-sdd uses takt's state-machine-based workflow control to deterministically manage AI agent execution paths.

• Declarative Workflow Control — Define AI agent execution order and transition conditions declaratively in pieces (YAML). While AI output itself is non-deterministic, "which step, in what order, under what conditions" is deterministically controlled by YAML rules. Workflows progress as state machines, not free-form chat.
• Faceted Prompting — Separate prompts into 5 independent concerns (Persona / Policy / Instruction / Knowledge / Output Contract). Each facet is reusable and swappable, shareable across pieces. Eliminates duplication of monolithic prompts and improves maintainability.
• Multi-stage Validation — Place validation gates at each phase: requirements, design, and implementation. Gap analysis, design review (GO/NO-GO decisions), and parallel architecture/QA/implementation reviews detect quality issues early and minimize rework.
• Loop Detection and Supervisory Control — Automatically detect repetitive patterns like plan→implement and review→fix. When thresholds are exceeded, a supervisor intervenes to assess progress and automatically escalates unproductive loops.
• Adaptive Batch Implementation — Analyze inter-task dependencies and automatically choose between sequential and parallel execution. Independent tasks are processed in parallel by multiple workers.
• Provider Agnostic — The same piece definitions work across different providers such as Claude and Codex.

Prerequisites

• Node.js 22+ (takt is automatically added to devDependencies during installation)

Installation

To add the SDD workflow to your project, run the following in your project root:

npx create-takt-sdd

For Japanese facets and messages:

npx create-takt-sdd --lang ja

To install a specific version or the latest release:

npx create-takt-sdd --tag latest
npx create-takt-sdd --tag 0.1.2

The installer sets up the following:

• .takt/ — Pieces (YAML workflows) and facets in the selected language (--lang)
• package.json — npm scripts for each phase + takt as devDependency

Options:

When package.json already exists, only npm scripts are merged (existing scripts are not overwritten).

Adding Individual Skills

TAKT skills now live in j5ik2o/ai-tools. You can install them individually using npx skills add:

npx -y skills add j5ik2o/ai-tools --skill takt-analyzer
npx -y skills add j5ik2o/ai-tools --skill takt-facet-builder
npx -y skills add j5ik2o/ai-tools --skill takt-optimizer
npx -y skills add j5ik2o/ai-tools --skill takt-piece-builder
npx -y skills add j5ik2o/ai-tools --skill takt-task-builder

Kiro Compatibility Workflow

SDD executes the following phases in order:

Use the full-auto piece cc-sdd-full to run Phases 1–5 in a single automated sequence.

Full-Auto Execution

Run requirements → gap analysis → design → design validation → implementation → implementation validation all at once.

npm run cc-sdd:full -- "description of requirements..."

Phase-by-Phase Execution

Run each phase workflow individually, allowing human intervention between phases.

# Phase 1: Requirements generation
npm run cc-sdd:requirements -- "description of requirements..."
# Check the {feature} name in .kiro/specs/{feature}

# Phase 1.5: Gap analysis (only when existing code exists)
npm run cc-sdd:validate-gap -- "feature={feature}"

# Phase 2: Design generation
npm run cc-sdd:design -- "feature={feature}"

# Phase 2.5: Design validation (auto-fix → re-validate on NO-GO)
npm run cc-sdd:validate-design -- "feature={feature}"

# Phase 3: Task generation
npm run cc-sdd:tasks -- "feature={feature}"

# Phase 4: Implementation
npm run cc-sdd:impl -- "feature={feature}"

# Phase 5: Implementation validation (auto-fix → re-validate on failure)
npm run cc-sdd:validate-impl -- "feature={feature}"

takt --pipeline --skip-git -w cc-sdd-full -t "description of requirements..."
takt --pipeline --skip-git -w cc-sdd-requirements -t "description of requirements..."
takt --pipeline --skip-git -w cc-sdd-validate-gap -t "feature={feature}"
takt --pipeline --skip-git -w cc-sdd-design -t "feature={feature}"
takt --pipeline --skip-git -w cc-sdd-validate-design -t "feature={feature}"
takt --pipeline --skip-git -w cc-sdd-tasks -t "feature={feature}"
takt --pipeline --skip-git -w cc-sdd-impl -t "feature={feature}"
takt --pipeline --skip-git -w cc-sdd-validate-impl -t "feature={feature}"

For interactive mode, run takt -w {piece-name}.

Output Files

Artifacts from each phase are output to .kiro/specs/{feature}/. The format is compatible with Kiro specifications.

Steering (Project Memory Management)

Separate from the SDD workflow, pieces are provided to manage .kiro/steering/ as project memory.

steering

Analyzes the codebase and records the project's purpose, tech stack, and structural patterns in .kiro/steering/. Runs in bootstrap mode on first execution, and in sync mode afterwards to detect drift from the code.

For greenfield projects (no existing code), skeleton files with placeholders are generated so developers can fill in their decisions.

npm run cc-sdd:steering -- "sync steering"

# Greenfield: specify product direction and tech choices upfront
npm run cc-sdd:steering -- "REST API server with TypeScript, Express, PostgreSQL"

steering-custom

Creates steering files for specific domains such as architecture policies, API standards, and testing strategies. Templates are available in .takt/knowledge/steering-custom-template-files/.

npm run cc-sdd:steering:custom -- "architecture"
# Specify the {name} from .takt/knowledge/steering-custom-template-files/{name}.md

Available templates:

Greenfield Support (Projects with No Existing Code)

Both cc-sdd:steering and cc-sdd:steering-custom support greenfield projects. Skeleton files can be generated even when the codebase is empty. Steering files are generated based on the template structure with placeholders ([choice], [rationale], etc.) for developers to fill in.

To specify policies upfront, add them to the command:

# Generate core steering skeletons (product.md / tech.md / structure.md)
npm run cc-sdd:steering -- "generate steering"

# Specify product direction and tech choices upfront
npm run cc-sdd:steering -- "REST API server with TypeScript, Express, PostgreSQL"

# Custom steering: specify architecture policies
npm run cc-sdd:steering:custom -- "architecture: hexagonal architecture, actor model"

# Custom steering: specify testing strategy
npm run cc-sdd:steering:custom -- "testing: Vitest, E2E with Playwright, 80%+ coverage"

# Custom steering: specify database policies
npm run cc-sdd:steering:custom -- "database: PostgreSQL, Prisma ORM, automated migrations"

# Custom steering: generate skeleton only (fill in manually later)
npm run cc-sdd:steering:custom -- "testing"

Generated steering files are automatically referenced during design phases (sdd:design, sdd:validate-design, etc.).

OpenSpec Compatibility Workflow

Separate from the SDD workflow, an OpenSpec-based change management workflow is provided. This workflow manages structured changes through proposal → implementation → archival phases.

Full-Auto Execution

npm run opsx:full -- "description of change"

Phase-by-Phase Execution

# Create a change and generate artifacts
npm run opsx:propose -- "change-name"

# Implement tasks
npm run opsx:apply -- "change-name"

# Archive completed change
npm run opsx:archive -- "change-name"

# Interactive exploration (independent, thinking-only mode)
npm run opsx:explore

OpenSpec Configuration

The openspec/config.yaml file defines the schema and optional project context:

schema: spec-driven

# Optional: project context shown to AI when creating artifacts
# context: |
#   Tech stack: TypeScript, React, Node.js

# Optional: per-artifact rules
# rules:
#   proposal:
#     - Keep proposals under 500 words

Changes are stored in openspec/changes/<name>/ and archived to openspec/changes/archive/.

Project Structure

.takt/
├── en/                      # English facets and pieces
│   ├── pieces/              # Piece definitions (workflow YAML)
│   ├── personas/            # Persona facets
│   ├── policies/            # Policy facets
│   ├── instructions/        # Instruction facets
│   ├── knowledge/           # Knowledge facets
│   └── output-contracts/    # Output contract facets
└── ja/                      # Japanese facets and pieces
    ├── pieces/              # ピース定義（ワークフロー YAML）
    ├── personas/            # ペルソナファセット
    ├── policies/            # ポリシーファセット
    ├── instructions/        # インストラクションファセット
    ├── knowledge/           # ナレッジファセット
    └── output-contracts/    # 出力契約ファセット
references/
└── okite-ai/                # AI rules collection (submodule)
scripts/
├── takt.sh                  # takt execution wrapper
└── opsx-cli.sh              # OpenSpec CLI (change management)

Inspired By

This project is inspired by the following projects:

• Kiro - Amazon's SDD-based AI development environment
• cc-sdd - SDD tool supporting multiple AI coding agents
• OpenSpec - Lightweight spec-driven framework for AI coding assistants