# SpecBind Repository Guidelines

## Repository Purpose

- This repository develops SpecBind itself. It is not a consumer project using SpecBind to deliver an application.
- SpecBind was bootstrapped from `gotalab/cc-sdd` and has been detached from the GitHub fork network.
- Treat inherited cc-sdd code and documentation as migration inputs, not as the final SpecBind interface.
- Prefer SpecBind-specific commands, workflows, terminology, and compatibility decisions over drop-in cc-sdd compatibility unless compatibility is explicitly required.

## Source Layout

- `tools/cc-sdd/src/` — inherited TypeScript CLI retained as a migration and comparison oracle
- `tools/cc-sdd/test/` — inherited TypeScript automated tests
- `tools/cc-sdd/schemas/` — inherited hand-authored schema snapshots retained as migration inputs
- `tools/cc-sdd/templates/` — current files installed into consumer projects
- `tools/specbind/` — canonical Rust CLI workspace
- `tools/specbind/src/` — Rust CLI implementation
- `tools/specbind/src/yaml.rs` — restricted YAML-to-neutral-JSON parser boundary
- `tools/specbind/src/schema/` — authoritative versioned structured-artifact wire models and schema generator
- `tools/specbind/src/schema/runtime.rs` — parser, schema selection, validation, and wire-deserialization load boundary
- `tools/specbind/src/domain/` — artifact-local semantic validation and validated domain wrappers
- `tools/specbind/src/artifacts.rs` — spec-local OKF discovery, metadata profiles, inventory, gate-input resolution, and traceability I/O
- `tools/specbind/src/requirements.rs` — Markdown AST validation and canonical Requirement ID extraction
- `tools/specbind/src/design.rs` — Design emphasis-marker extraction and Front Matter traceability equality
- `tools/specbind/src/traceability.rs` — cross-artifact Requirement existence plus active Design and Task coverage
- `tools/specbind/src/contract.rs` — canonical Contract Markdown parsing and artifact-local semantic validation
- `tools/specbind/src/contract_graph.rs` — project-wide Contract reference, ownership-overlap, and dependency-cycle read model
- `tools/specbind/src/roadmap.rs` — active Roadmap parsing, DAG validation, and normalized cross-spec scope projection
- `tools/specbind/src/cross_spec_review.rs` — strict review candidate and authoritative Contract-first input revision resolution
- `tools/specbind/src/fingerprint.rs` — Markdown and normalized typed task-plan fingerprint producers
- `tools/specbind/src/freshness.rs` — gate-local requirements, design, and tasks freshness evaluation
- `tools/specbind/src/release_readiness.rs` — stateless whole-milestone release readiness and target-only Git safety validation
- `tools/specbind/src/release_log.rs` — strict release-summary JSON and localized canonical OKF `log.md` updates
- `tools/specbind/src/release_finalize.rs` — ordered, guarded, retry-safe whole-milestone finalization
- `tools/specbind/src/completion/` — Spec and Direct completion candidate validation, guarded transitions, and shared preflight checks
- `tools/specbind/src/repository.rs` — installed-Git process adapter shared by lifecycle and status read models
- `tools/specbind/src/guarded_fs.rs` — regular-file guards and atomic replacement for SpecBind-owned state
- `tools/specbind/src/milestone.rs` — guarded active-Roadmap metadata mutations such as release binding
- `tools/specbind/src/release.rs` — portable release labels and case-insensitive archive-target collision resolution
- `tools/specbind/schemas/` — generated, checked-in Draft 2020-12 distribution schemas
- `tools/specbind/tests/` — Rust CLI integration tests
- `.github/workflows/rust.yml` — Windows and Linux Rust verification
- [`docs/current-skill-index.md`](docs/current-skill-index.md) — lightweight index of the skill set currently generated by the CLI
- [`docs/current-artifact-index.md`](docs/current-artifact-index.md) — lightweight index of files currently installed or maintained by the CLI and skills
- [`docs/design/target-skill-catalog.md`](docs/design/target-skill-catalog.md) — working catalog for proposed skill names and responsibilities
- [`docs/design/target-artifact-catalog.md`](docs/design/target-artifact-catalog.md) — proposed artifact ownership and lifecycle
- [`docs/design/target-workflows.md`](docs/design/target-workflows.md) — proposed user journeys and responsibility boundaries
- [`docs/design/active-spec-lifecycle.md`](docs/design/active-spec-lifecycle.md) — detailed draft for active specs and milestone finalization
- [`docs/design/spec-state-machine.md`](docs/design/spec-state-machine.md) — draft per-spec states, events, invalidation rules, and transition diagram
- [`docs/design/cli-agent-boundary.md`](docs/design/cli-agent-boundary.md) — proposed boundary between bundled deterministic CLI operations and agent skills
- [`docs/design/cross-spec-contracts.md`](docs/design/cross-spec-contracts.md) — detailed draft for persistent cross-spec seam manifests and contract-first review
- [`docs/design/rust-cli-migration.md`](docs/design/rust-cli-migration.md) — working migration plan from the TypeScript installer to the complete Rust CLI
- [`docs/design/decisions/0002-project-release-adapter.md`](docs/design/decisions/0002-project-release-adapter.md) — accepted core-plus-project-adapter release direction
- [`docs/design/decisions/0003-active-requirement-set.md`](docs/design/decisions/0003-active-requirement-set.md) — accepted storage contract for current milestone Requirement IDs
- [`docs/design/decisions/0004-release-history-layout.md`](docs/design/decisions/0004-release-history-layout.md) — accepted per-spec changelog and roadmap archive layout
- [`docs/design/decisions/0005-active-change-abandonment.md`](docs/design/decisions/0005-active-change-abandonment.md) — accepted scope removal, abandonment, and rollback boundaries
- [`docs/design/decisions/0006-rust-cli.md`](docs/design/decisions/0006-rust-cli.md) — accepted direction to reimplement the complete SpecBind CLI in Rust
- [`docs/design/decisions/0007-spec-root.md`](docs/design/decisions/0007-spec-root.md) — accepted configurable spec root with `.specbind` as the new-project default
- [`docs/design/decisions/0008-customization-surface.md`](docs/design/decisions/0008-customization-surface.md) — accepted shared templates and rules as the stable project customization surface
- [`docs/design/decisions/0009-milestone-cli-boundary.md`](docs/design/decisions/0009-milestone-cli-boundary.md) — accepted discovery-plus-Rust-CLI milestone responsibility boundary
- [`docs/design/decisions/0010-release-execution-boundary.md`](docs/design/decisions/0010-release-execution-boundary.md) — accepted AI adapter execution and Rust CLI release-finalization boundary
- [`docs/design/decisions/0011-cross-spec-contract.md`](docs/design/decisions/0011-cross-spec-contract.md) — accepted persistent contract manifest and contract-first cross-spec review direction
- [`docs/design/decisions/0012-delegated-approval.md`](docs/design/decisions/0012-delegated-approval.md) — accepted explicit-versus-delegated gate approval and non-interactive execution boundary
- [`docs/design/decisions/0013-structured-task-artifact.md`](docs/design/decisions/0013-structured-task-artifact.md) — accepted structured `tasks.yaml` source-of-truth direction
- [`docs/design/decisions/0014-structured-spec-metadata.md`](docs/design/decisions/0014-structured-spec-metadata.md) — accepted structured `spec.yaml` source-of-truth direction
- [`docs/design/decisions/0015-runtime-schema-layout.md`](docs/design/decisions/0015-runtime-schema-layout.md) — accepted versioned runtime-schema location and validation layers
- [`docs/design/decisions/0016-fingerprint-value-format.md`](docs/design/decisions/0016-fingerprint-value-format.md) — accepted tagged lowercase SHA-256 fingerprint representation
- [`docs/design/decisions/0017-requirements-gate-inputs.md`](docs/design/decisions/0017-requirements-gate-inputs.md) — accepted requirements-gate fingerprint boundary excluding `brief.md`
- [`docs/design/decisions/0018-gate-input-comparison.md`](docs/design/decisions/0018-gate-input-comparison.md) — accepted Markdown normalization, Requirement ID snapshot, and task-plan projection boundaries
- [`docs/design/decisions/0019-task-ordering-and-dependencies.md`](docs/design/decisions/0019-task-ordering-and-dependencies.md) — accepted ordered task execution with sparse dependency exceptions
- [`docs/design/decisions/0020-positional-task-ids.md`](docs/design/decisions/0020-positional-task-ids.md) — accepted cc-sdd-style positional numeric Task IDs
- [`docs/design/decisions/0021-optional-completion-criteria.md`](docs/design/decisions/0021-optional-completion-criteria.md) — accepted dedicated, conditionally optional task completion criteria
- [`docs/design/decisions/0022-no-optional-tasks.md`](docs/design/decisions/0022-no-optional-tasks.md) — accepted removal of inherited optional tasks from `tasks.yaml` v1
- [`docs/design/decisions/0023-sparse-task-plan-shape.md`](docs/design/decisions/0023-sparse-task-plan-shape.md) — accepted strict sparse group and executable-task plan objects
- [`docs/design/decisions/0024-sparse-task-execution-state.md`](docs/design/decisions/0024-sparse-task-execution-state.md) — accepted sparse persisted completed and blocked task states
- [`docs/design/decisions/0025-task-read-model.md`](docs/design/decisions/0025-task-read-model.md) — accepted human and JSON CLI projections for task status and detail
- [`docs/design/decisions/0026-runtime-implementation-notes.md`](docs/design/decisions/0026-runtime-implementation-notes.md) — accepted persistent free-form implementation memory for later agents
- [`docs/design/decisions/0027-spec-local-task-dependencies.md`](docs/design/decisions/0027-spec-local-task-dependencies.md) — accepted local-only Task IDs with roadmap and contract routing for cross-spec dependencies
- [`docs/design/decisions/0028-task-plan-fingerprint.md`](docs/design/decisions/0028-task-plan-fingerprint.md) — accepted normalized typed-plan projection and canonical fingerprint algorithm
- [`docs/design/decisions/0029-completion-validation-handshake.md`](docs/design/decisions/0029-completion-validation-handshake.md) — accepted clean Git revision handshake for guarded completion validation
- [`docs/design/decisions/0030-persist-only-accepted-completion-evidence.md`](docs/design/decisions/0030-persist-only-accepted-completion-evidence.md) — accepted current-state-only storage for successful completion evidence
- [`docs/design/decisions/0031-project-scoped-revision-format.md`](docs/design/decisions/0031-project-scoped-revision-format.md) — accepted scalar Git implementation revision interpreted from project context
- [`docs/design/decisions/0032-gate-local-freshness-chain.md`](docs/design/decisions/0032-gate-local-freshness-chain.md) — accepted gate-local revision ownership and cascading freshness semantics
- [`docs/design/decisions/0033-completion-mechanical-checks.md`](docs/design/decisions/0033-completion-mechanical-checks.md) — accepted concise categorized command evidence for successful completion validation
- [`docs/design/decisions/0034-do-not-persist-semantic-pass-flags.md`](docs/design/decisions/0034-do-not-persist-semantic-pass-flags.md) — accepted semantic validation protocol without redundant persisted pass flags
- [`docs/design/decisions/0035-roadmap-owned-cross-spec-review.md`](docs/design/decisions/0035-roadmap-owned-cross-spec-review.md) — accepted roadmap ownership for contract-impact and downstream-review evidence
- [`docs/design/decisions/0036-rfc3339-gate-timestamps.md`](docs/design/decisions/0036-rfc3339-gate-timestamps.md) — accepted timezone-qualified RFC 3339 format for gate timestamps
- [`docs/design/decisions/0037-minimal-completion-evidence-shape.md`](docs/design/decisions/0037-minimal-completion-evidence-shape.md) — accepted strict three-field completion evidence object
- [`docs/design/decisions/0038-design-gate-inputs.md`](docs/design/decisions/0038-design-gate-inputs.md) — accepted design and contract fingerprint inputs for the design gate
- [`docs/design/decisions/0039-minimal-tasks-gate-evidence.md`](docs/design/decisions/0039-minimal-tasks-gate-evidence.md) — accepted minimal approval evidence for the normalized task-plan projection
- [`docs/design/decisions/0040-state-gate-evidence-invariants.md`](docs/design/decisions/0040-state-gate-evidence-invariants.md) — accepted sparse cumulative evidence and semantic state-to-gate invariants
- [`docs/design/decisions/0041-no-per-spec-change-id.md`](docs/design/decisions/0041-no-per-spec-change-id.md) — accepted milestone-plus-spec identity without a separate per-spec change ID
- [`docs/design/decisions/0042-sequential-milestone-id.md`](docs/design/decisions/0042-sequential-milestone-id.md) — superseded project-sequential milestone ID decision
- [`docs/design/decisions/0043-uuidv7-milestone-id.md`](docs/design/decisions/0043-uuidv7-milestone-id.md) — accepted branch-safe UUID v7 milestone IDs
- [`docs/design/decisions/0044-minimal-spec-root.md`](docs/design/decisions/0044-minimal-spec-root.md) — accepted minimal strict `spec.yaml` root and active-change object

The root `.kiro/` directory is not used to develop SpecBind and is intentionally ignored. Current consumer-facing `.kiro/` files must be maintained under `tools/cc-sdd/templates/shared/settings/` until the Rust templates replace them. Do not require `/kiro-*` or `$kiro-*` workflows for this repository unless the user explicitly requests one.

## Development Workflow

- Follow the user's requested scope and make changes directly unless they explicitly request a SpecBind specification workflow.
- This repository currently uses a direct-to-`main` personal-development workflow. Unless the user explicitly asks to stop before committing or pushing, commit each completed unit of work to `main` and push it to `origin/main` before reporting completion.
- Keep changes narrow and preserve unrelated work in the worktree.
- When changing installed behavior, update the relevant source, templates, tests, and documentation together.
- Keep Claude Code and Codex templates aligned where they implement the same contract, while preserving platform-specific invocation syntax and capabilities.
- For adding or extending coding-agent support, follow the SOP in `.agents/skills/specbind-new-agent/SKILL.md`.

## Rust Toolchain and Dependencies

- `tools/specbind/rust-toolchain.toml` pins the supported development toolchain and required `rustfmt` and `clippy` components. Do not silently change the pinned toolchain or `rust-version`.
- Windows MSVC validation requires Visual Studio Build Tools with the C++ workload and a Windows SDK. Do not switch the canonical Windows target to GNU merely to avoid this prerequisite.
- `tools/specbind/Cargo.lock` is committed because SpecBind is a distributed application.
- Keep workspace dependency versions and feature selection centralized in `tools/specbind/Cargo.toml`. Disable broad default features where the accepted product contract does not need them, especially networking and terminal styling.
- Prefer focused external crates behind SpecBind-owned module boundaries. Do not expose third-party result or model types as public artifact or CLI contracts.
- Use stable Rustfmt options only. Configure lint levels in the workspace manifest and add narrowly scoped `allow` entries only with a concrete reason.
- Treat versioned wire models under `tools/specbind/src/schema/` as the structural source of truth. A structural change must update the accepted design, wire model, generated schema, and conformance fixtures together.
- Regenerate schemas with `cargo run --example generate_schemas`; never hand-edit generated files under `tools/specbind/schemas/`.

## Validation

Run Rust verification from `tools/specbind/`:

```sh
cargo fmt --all -- --check
cargo run --example generate_schemas -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
cargo build --workspace --release
```

Run inherited TypeScript verification from `tools/cc-sdd/`:

```sh
npm test
npm run build
```

- Add or update focused tests for behavior changes.
- Before reporting completion, inspect the final diff and confirm generated or installed templates still match their intended consumer environment.

## Language

- Respond to the user in Japanese unless they request another language.
- Preserve the language of an existing document unless the task requires translation.
- English and Japanese are the only officially supported product languages during the current stabilization phase.