Spec-kit Coding

Spec-Kit Coding -- OpenClaw Orchestrator

Repo: Staok/spec-kit-coding-skill

Orchestrates the complete Spec-Driven Development workflow via github/spec-kit.

Covers: Engineering Implementation. Does not cover requirements discovery, operations/deployment, or cross-domain (SRE, security, etc.).

---

HARD CONSTRAINTS

READ FIRST, APPLY ALWAYS.

These constraints are non-negotiable. Do NOT require the user to repeat them.

Security

• Never transmit sensitive information to the network.
• Before any external action (API calls, sending data outside local machine), explain and ask for approval.
• Do not install third-party libraries or modify system config without asking first. If a new dependency is needed, explain why and get approval.
• Prefer reusing existing, proven, popular third-party solutions. Avoid reinventing the wheel. Keep tool usage simple and lean. Minimize dependency footprint.
• WARNING: As a principle, agents should be disabled in critical-path code, legacy system maintenance, and security-sensitive modules. Permitted only in low-risk scenarios such as prototyping, search, and documentation.

Feature Management / Quick Reference

• Starting a project, follow section: WORKFLOW, from STEP 1 to STEP 7.
• On first project creation, ask the user: auto-run the WORKFLOW (pause only for required confirmations), or confirm at each step.
• Add a new feature or modify an existing feature:
  • "add" / "new" / behavior no spec covers -> new feature -> section: STEP 5: Spec-Kit Phases / New Feature.
  • "change" / "modify" / changing existing behavior -> modify existing -> section: Feature Modification Entry Point.
• Each /speckit-specify invocation creates exactly ONE feature. If the user describes a messy, multi-concern requirement, split it first:
  • List each proposed feature with a short name and one-line summary.
  • Note dependencies between features.
  • Ask user to confirm the split before proceeding.
• When uncertain whether the user wants a new feature or a modification to an existing one, ASK. Do not guess. Present your organized analysis. Show several or both options concisely.
• For projects that have already been delivered or already exist, if a bug is reported, refer to section: Bug Fix Entry Point.

Communication

• Collect all unclear points first, then ask once. Avoid back-and-forth.
• Be efficient and concise. Output only necessary information.
• Remind the user how to think about the problem better; help improve prompt quality over time.

Documentation-First

• For spec/plan/tasks .etc phase docs (spec.md, plan.md, tasks.md): these are created via the speckit-* phases prior to implementation.
• For DEVLOG.md: update per implementation batch, and after every phase completion. DEVLOG must always reflect the latest state.
• For README.md Architecture: seed during plan phase. Update as a final step after all implementation completes (Step 5 and Step 6.3).
• Never reverse the order: docs first, code second.

Git Management

• During project init (Step 1), ASK whether to enable git. Record the answer.
• If enabled: git init, .gitignore, initial commit. Then commit after each phase completion and each implementation batch.
• If disabled: do not create or manage a git repository.
• The user may enable git at any later point. Once enabled, keep it on.

Context Isolation

• "Implement" (The whole Step 6 and Step 6.X) MUST run in fresh isolated sub-agent sessions. Never run implement in a session that has accumulated multiple prior phases.
• If tasks.md has more than ~15 items, split implementation into batches. Each batch = fresh sub-agent session.
• Better to over-split than to produce garbage from context saturation.

Session Interrupt

• If a session is interrupted mid-phase, do NOT assume which phase to restart from. Ask the user: "Restart from [interrupted-phase] or from [previous-completed-phase]?" If user is unsure, default to re-running the interrupted phase from the start.

---

WORKFLOW

STEP 0: Prerequisites (one-time per machine)

Run: bash ~/.openclaw/workspace/skills/spec-kit-coding/setup.sh

Ask user for confirmation before first run. This installs specify CLI, speckit-* skills, and auxiliary skills. Do NOT proceed until it reports all dependencies ready.

Options: --check-only (check without install), --force (force reinstall).

STEP 1: Project Init

1. Ask user for project path (default: current directory).
2. Ask: "Enable git management?"

In project directory from now on:

1. Run: specify init --here --integration claude --force --ignore-agent-tools --script sh --no-git
2. Clean up: rm -rf .claude CLAUDE.md (keep .specify/).
3. Verify: .specify/ exists by run test -d .specify && echo "OK: .specify/ exists", and skills .etc are present by run bash ~/.openclaw/workspace/skills/spec-kit-coding/setup.sh --check-only.
4. Follow the Git management section to do.

STEP 2: Create Project Docs

Create README.md and DEVLOG.md. Templates in Appendix A.

Key rules:

• README.md Architecture section: seed during plan phase (Step 5). Update as final (Step 6.3).
• DEVLOG.md: per-feature tracking. Each feature has its own phase history block. The Summary table is regenerated from Feature Detail blocks after every update -- do NOT manually edit the Summary section.

GATE: Confirm with user that docs look correct.

STEP 3: Coding Standards and UI Skill Check

Coding Standards (Checkpoint A -- before constitution)

Collect BOTH architecture principles AND coding style conventions in ONE prompt:

1. If user already provided documents/URLs/inline text earlier in the conversation, use them directly. Do NOT re-ask.
2. If not provided: detect languages from README.md SPEC Overview, then ask:

Use built-in coding standards as constitution reference?

Architecture & Design: spec-kit-coding/CodingGuidance/TopLevelCodingGuidance.md

[Per-language coding style skills listed here based on detected languages]

Coding Style (C++): spec-kit-coding/CodingGuidance/CppCodingStyle.md, spec-kit-coding/CodingGuidance/CppEngineeringFrameworkReference/, spec-kit-coding/CodingGuidance/DesignPattern/, external-skills/ecc-cpp-coding-standards [Similar for other languages, spec-kit-coding/external-skills/ecc-*]

Language-agnostic: spec-kit-coding/external-skills/ecc-coding-standards

• "Yes": include reference paths in constitution prompt, just ask to directly write the reference paths in constitution.md but Do NOT copy or re-write the reference files content.
• "No": generate concise generic guidance inline.
• "Partial": respect the user's selection.

Rules:

• Once confirmed, standards persist across all features in the project.
• Do NOT modify CodingGuidance/. Read-only except during skill updates.

UI Skill Check (Checkpoint B -- before plan, after constitution)

If the project involves UI, ask ONCE:

This project involves UI. Available frontend skills: spec-kit-coding/external-skills/ui-ux-pro-max-skill (design system), or spec-kit-coding/external-skills/ecc-*. Load relevant ones for plan/implement?

• "yes": sub-agents read chosen UI skills during plan and implement.
• "no": skip.

STEP 4: Grill Alignment

Before writing specs, align the agent's understanding with the project's domain. Use spec-kit-coding/external-skills/mattpocock-grill-with-docs.

Outputs:

• CONTEXT.md at project root: Domain glossary. Devoid of implementation details — it is a glossary, not a spec or scratch pad.
• docs/adr/: Architecture Decision Records (sparingly).

Runs once per project. Subsequent features reuse CONTEXT.md and ADRs.

GATE: Confirm with user that CONTEXT.md accurately captures the domain language and any created ADRs are correct.

STEP 5: Spec-Kit Phases / New Feature

Two paths available. Choose per-feature based on requirement clarity.

Production path (8 Phases -- for complex/ambiguous features):

constitution -> specify -> clarify -> checklist -> plan -> tasks -> analyze -> implement

Lean path (6 Phases -- for simple/well-understood features):

constitution -> specify -> clarify -> plan -> tasks -> implement

Each phase apply the corresponding skill spec-kit-coding/external-skills/speckit-*.

Rules:

• constitution runs once at project start. Subsequent features reuse it.
• Use CONTEXT.md terminology in specify, plan, tasks.
• clarify is ALWAYS run after specify (both paths). It catches ambiguities.
• Skip checklist and analyze on lean path.
• speckit-specify may generate an internal validation checklist as part of its own flow. This is NOT the standalone speckit-checklist step.

When to re-run constitution, only for:

• Adding a new programming language not previously covered
• Architecture-level changes that override existing principles

If git enabled: commit after every spec-Kit phases.

STEP 6: Implementation

MUST run in fresh isolated sessions. Use the spawn template below.

1. If tasks.md <= ~15 items and estimated code-gen calls <= ~12: single sub-agent.
2. Otherwise: split into batches. Each batch = fresh sub-agent session.
3. After each batch: sub-agent updates DEVLOG.md. If git enabled: commit.
4. Orchestrator tracks remaining tasks, spawns next batch.

Spawn Template

Copy this verbatim, filling in placeholders from the table:

You are  for feature - in project at .

CONTEXT BOUNDARY: You are a fresh isolated session. Focus EXCLUSIVELY on
feature -. The documents below are your sole source of truth.
Do NOT mix in details from other features, projects, or earlier batches.

Before , read these documents in order:
1. /CONTEXT.md (Domain glossary — if it exists)
2. /.specify/memory/constitution.md
3. /specs/-/* (All documents related to this feature)
4. /docs/adr/ (Architecture Decision Records — if any exist)
5. /README.md (Architecture section)


After completing your work:
- Update /DEVLOG.md
- If git management is enabled: git commit all changes
- Report back using the structured format below

Sub-Agent Report Format

Every sub-agent MUST end with:

## SUB-AGENT REPORT
- Role: 
- Feature: -
- Status: 
- Tasks Completed: 
- Tasks Remaining: 
- Issues Found: 
- Blockers: 
- Files Modified: 
- Summary: <1-2 sentences>

Orchestrator uses Status:

• SUCCESS -> proceed to next gate
• PARTIAL -> spawn continuation batch
• BLOCKED -> escalate to user
• FAILED -> diagnose; retry, rollback, or escalate

GATE: After all batches report SUCCESS, confirm with user before proceeding to Code Review.

STEP 6.1: Code Review

After code implementation.

Code review and fix. Ready the project for Testing.

Spawn a fresh isolated session using the spawn template (Step 6) with the "Code Review (Step 6.1)" column values.

After review:

1. Present findings to user.
2. Ask: "Which review findings should be addressed?"
3. Apply ONLY user-approved fixes.
4. Re-run review on changed files AND related files.
5. If new issues: repeat from step 1. Limit: 3 review-fix cycles total.
6. If issues persist after 3 cycles: stop. Report outstanding issues to the user; user may decide to record them in README.md Known Limitations / Issues and proceed.

STEP 6.2: Testing

Code testing and debugging and fix. Ready the project for Final Review.

Spawn a fresh isolated session using the spawn template (Step 6) with the "Test (Step 6.2)" column values.

STEP 6.3: Final Review

After STEP 6.2: Testing.

Optimization & Doc Sync + Complexity Audit. Ready the project for STEP 7: Delivery Check.

Perform these actions in order. Do NOT skip any.

1. Re-read all modified source files for the feature.

2. Check for:

   1. Algorithmic improvements (better complexity).
   2. Redundant allocations or copies.
   3. Unnecessary dependencies.
   4. Dead code or unreachable branches.
   5. .etc

3. Complexity Delta. Inspect the actual diff and report:

   Complexity Delta:
   - Files over 1200 lines:
   - Files newly crossing 1200 lines:
   - Largest touched file delta:
   - Largest touched function/block:
   - New branches/fallbacks/adapters:
   - Retired branches/fallbacks/adapters:
   - Net entropy: decreased | stable | increased-with-justification
   - Required follow-up:
   
   Complexity Governance Suggestion:
   - Recommendation: none | monitor | schedule-refactor | extract helper | split owner | open follow-up
   - Why:
   - Suggested scope:
   - Timing:
   

   Skip for trivial changes (tests-only, generated, formatting, etc.).

4. Record findings in README.md -> Features Plan / TODOs (NOT as TODO comments in source). Format: - [ ] [category] description (file: path:line-range) Categories: optimization, robustness, clarity, security, perf.

5. Present candidates to user:

   Optimization candidates found: Implement now (low risk, high impact):

   • [item]

   Defer (tracked in README):

   • [item] Which "implement now" items should I apply?

6. If user approves code changes: a. Apply changes. b. Full clean rebuild. c. Run ALL tests. d. If any test fails -> return to STEP 6.2: Testing. e. If all pass -> continue. f. If 3 cycles of regression->test->debug fail to converge: escalate to user.

7. Update README.md Architecture section to reflect what was actually built.

8. Update DEVLOG.md -- verify all phases and dates are current.

9. If git enabled: commit.

STEP 7: Delivery Check

Run through this checklist. Every item must be checked:

• All required speckit-* phases completed or skipped (lean skips checklist, analyze -- this is expected).

• STEP 4 Grill Alignment completed (CONTEXT.md + any ADRs created).

• Code review(If asked) completed and approved fixes applied.

• All tests pass.

• Source tree is clean (no temp files, no build artifacts in source dirs).

• Complexity Delta checked (Step 6.3 item 3). Net entropy not increased without justification.

• Whole README.md is up-to-date.

  Especially: README.md Architecture section is up-to-date. Optimization findings tracked in README.md Features Plan / TODOs section.

• DEVLOG.md reflects all completed phases.

• All hard constraints from section HARD CONSTRAINTS respected.

• If git enabled: all changes committed.

• Evidence Card. Fill out ONE evidence card covering all verification:

  Evidence Card:
  - Command / Check: 
  - Exit Status: 
  - Covered: 
  - Not Covered: 
  - Residual Risk: 
  - Confidence: A | B | C
  

  Confidence grades:

  • A: Direct verification + regression, no unknowns
  • B: Direct verification, bounded residual risk
  • C: Partial verification only, not closed — do NOT claim done

  A claim of completion without evidence is NOT acceptable. Words like "should", "probably", "seems to" are Red Flags — STOP and verify.

GATE: Present delivery summary to user, including the filled Evidence Card.

Feature Modification Entry Point

When the user wants to modify an existing feature, route by change type:

DEVLOG records a new phase cycle regardless of tier.

All path above at end must go section: STEP 7: Delivery Check.

Bug Fix Entry Point

When user reports a bug:

1. Read the feature's spec.md, plan.md, and relevant source files.
2. Determine if the bug is:
   • Spec gap (behavior not defined) -> clarify -> plan -> implement.
   • Implementation error (code disagrees with spec) -> fix directly.
3. Then go section: STEP 6.2: Testing
4. Then go section: STEP 6.3: Final Review
5. Go section: STEP 7: Delivery Check.

---

TROUBLESHOOTING

---

APPENDIX A: README.md and DEVLOG.md Templates

README.md Template

Create /README.md:

# 

## Project Introduction


## Key Features

<!-- Completed features (use `- ` list, NOT checkboxes).
     This section describes what the project DOES today. -->
- 
- 

## SPEC Overview

- Type: 
- Language(s) / Version(s): 
- Build: 
- Dependencies: 
- License: 

## Local Build

### Prerequisites
- <...>

### Build Commands
```bash
# Debug
<...>
# Release
<...>
```

## Usage Examples

```bash
# Basic usage
<...>
# With options
<...>
```

## Architecture

**Living document.** Seeded during plan phase (Step 5). Updated after all
implementation completes (Step 6.3).


### Platform / Component Details


## Known Limitations / Issues

- 
- 

## Features Plan / TODOs

<!-- Planned/upcoming features (use `- [ ]` checkboxes).
     This section describes what the project WILL DO in the future.
     Move items to Key Features (as `- ` bullets) when implemented. -->
- [ ] 
- [ ] ...

## Spec-Driven Development Workflow And More

This project uses [github/spec-kit](https://github.com/github/spec-kit)
orchestrated via the spec-kit-coding OpenClaw skill. Progress tracked in
DEVLOG.md.

DEVLOG.md Template

Create /DEVLOG.md with per-feature progress tracking.

All dates in DEVLOG.md MUST use YYYY-MM-DD HH:MM format.

Feature name is - that the dir name from /specs dir.

# Development Log -- 

## Feature Progress Summary

| Feature | Specify | Clarify | Checklist | Plan | Tasks | Analyze | Implement | Updated |
|---------|---------|---------|-----------|------|-------|---------|-----------|---------|
| -- | -- | -- | -- | -- | -- | -- | -- | -- |

Legend: [ ] pending | [~] in-progress | [√] complete | [>] skipped | [!] blocked

## Feature Details

<!-- FEATURE BLOCK START -->
### -

- Description: 
- Current Phase: 
- Last Updated: 

**Phase History**:

| Phase | Date | Status | Notes |
|-------|------|--------|-------|
| speckit-specify | | [ ] | |
| speckit-clarify | | [ ] | |
| speckit-checklist | | [ ] | |
| speckit-plan | | [ ] | |
| speckit-tasks | | [ ] | |
| speckit-analyze | | [ ] | |
| speckit-implement | | [ ] | |
<!-- FEATURE BLOCK END -->

## Global Notes

- Constitution: 
- Project init: 
- 

Rules:

• After each phase completes: update the Feature Detail block (Phase History table + Current Phase + Last Updated).
• After updating any Feature Detail: regenerate the Summary table from all Feature Detail blocks. Never manually edit the Summary section.
• When re-entering a feature (modification): add a new row to its Phase History.
• If starting a new feature before finishing a previous one: per-feature tracking keeps them independent.

---

APPENDIX B: Speckit Skills Reference

These are installed to external-skills/ by setup.sh (Step 0):

APPENDIX C: Auxiliary Skills Reference

All under external-skills/. Invoked as needed in review/test/ui .etc. See external-skills/MANIFEST.md for complete listing.