From 3be8d770be791ab5b4df95125895607b20f66460 Mon Sep 17 00:00:00 2001 From: "shaoding.zw" Date: Wed, 8 Apr 2026 18:20:19 +0800 Subject: [PATCH] chore: consolidate spec/agent tooling and add skill mirror generation Move specs/ content into docs/ to consolidate all project documentation under a single directory. Remove specs/ entirely, merge specs/AGENTS.md into top-level AGENTS.md, and update all path references in skills, constitution, templates, and module specs. --- .agents/skills/README.md | 120 +-- .agents/skills/archive/SKILL.md | 78 ++ .agents/skills/dev-workflow/SKILL.md | 54 ++ .agents/skills/speckit-analyze/SKILL.md | 87 -- .agents/skills/speckit-archive/SKILL.md | 93 -- .agents/skills/speckit-checklist/SKILL.md | 86 -- .agents/skills/speckit-clarify/SKILL.md | 190 ----- .agents/skills/speckit-constitution/SKILL.md | 87 -- .agents/skills/speckit-dev-workflow/SKILL.md | 103 --- .agents/skills/speckit-implement/SKILL.md | 112 --- .agents/skills/speckit-plan/SKILL.md | 95 --- .agents/skills/speckit-specify/SKILL.md | 186 ---- .agents/skills/speckit-tasks/SKILL.md | 153 ---- .agents/skills/speckit-taskstoissues/SKILL.md | 89 -- .agents/tooling/generate_skill_mirrors.py | 205 +++++ .claude/skills/archive/SKILL.md | 19 + .claude/skills/dev-workflow/SKILL.md | 14 + .../skills/dmir-compiler-analysis/SKILL.md | 14 + .claude/skills/dtvm-perf-profile/SKILL.md | 14 + .gitignore | 5 + .specify/memory/constitution.md | 40 +- .specify/scripts/bash/check-prerequisites.sh | 166 ---- .specify/scripts/bash/check-worktree.sh | 31 - .specify/scripts/bash/common.sh | 209 ----- .specify/scripts/bash/create-new-feature.sh | 353 -------- .specify/scripts/bash/setup-plan.sh | 60 -- .specify/scripts/bash/update-agent-context.sh | 797 ------------------ .specify/templates/agent-file-template.md | 28 - .specify/templates/checklist-template.md | 40 - .specify/templates/plan-template.md | 102 --- .specify/templates/spec-template.md | 135 --- .specify/templates/tasks-template.md | 246 ------ AGENTS.md | 71 +- .../add-evmc-vm-interface-lib/design.md | 0 .../add-evmc-vm-interface-lib/proposal.md | 0 .../specs/evmc-vm-interface/spec.md | 0 .../add-evmc-vm-interface-lib/tasks.md | 0 .../2026-02/add-clz-opcode/proposal.md | 0 .../specs/evm-execution/spec.md | 0 .../add-clz-opcode/specs/evm-jit/spec.md | 0 .../_archive/2026-02/add-clz-opcode/tasks.md | 0 .../add-jit-suitability-checker/design.md | 0 .../add-jit-suitability-checker/proposal.md | 0 .../specs/evm-jit/spec.md | 0 .../add-jit-suitability-checker/tasks.md | 0 .../2026-03/add-evm-jit-fallback/design.md | 0 .../2026-03/add-evm-jit-fallback/proposal.md | 0 .../specs/evm-execution/spec.md | 0 .../specs/evm-jit-fallback/spec.md | 0 .../2026-03/add-evm-jit-fallback/tasks.md | 0 .../design.md | 0 .../proposal.md | 6 +- .../specs/evm-jit/spec.md | 0 .../update-evm-memory-block-precheck/tasks.md | 0 {specs => docs}/_archive/README.md | 4 +- {specs => docs}/architecture/README.md | 0 docs/changes/README.md | 58 ++ docs/changes/template-light.md | 24 + docs/changes/template.md | 50 ++ {specs => docs}/code-style/README.md | 0 {specs => docs}/data-model/README.md | 0 {specs => docs}/modules/README.md | 0 {specs => docs}/modules/action/data-model.md | 0 {specs => docs}/modules/action/spec.md | 0 {specs => docs}/modules/cli/data-model.md | 0 {specs => docs}/modules/cli/spec.md | 0 {specs => docs}/modules/common/data-model.md | 0 {specs => docs}/modules/common/spec.md | 0 .../modules/compiler/data-model.md | 0 {specs => docs}/modules/compiler/spec.md | 2 +- {specs => docs}/modules/evm/data-model.md | 0 {specs => docs}/modules/evm/spec.md | 0 {specs => docs}/modules/host/data-model.md | 0 {specs => docs}/modules/host/spec.md | 0 .../modules/platform/data-model.md | 0 {specs => docs}/modules/platform/spec.md | 0 {specs => docs}/modules/runtime/data-model.md | 0 {specs => docs}/modules/runtime/spec.md | 0 .../modules/rust-bindings/data-model.md | 0 {specs => docs}/modules/rust-bindings/spec.md | 0 .../modules/singlepass/data-model.md | 0 {specs => docs}/modules/singlepass/spec.md | 2 +- {specs => docs}/modules/tests/data-model.md | 0 {specs => docs}/modules/tests/spec.md | 8 +- {specs => docs}/modules/tools/spec.md | 6 +- {specs => docs}/modules/utils/data-model.md | 0 {specs => docs}/modules/utils/spec.md | 0 .../modules/vm-interface/data-model.md | 0 {specs => docs}/modules/vm-interface/spec.md | 0 {specs => docs}/testing/README.md | 0 specs/AGENTS.md | 51 -- specs/README.md | 69 -- specs/features/README.md | 18 - 93 files changed, 642 insertions(+), 3738 deletions(-) create mode 100644 .agents/skills/archive/SKILL.md create mode 100644 .agents/skills/dev-workflow/SKILL.md delete mode 100644 .agents/skills/speckit-analyze/SKILL.md delete mode 100644 .agents/skills/speckit-archive/SKILL.md delete mode 100644 .agents/skills/speckit-checklist/SKILL.md delete mode 100644 .agents/skills/speckit-clarify/SKILL.md delete mode 100644 .agents/skills/speckit-constitution/SKILL.md delete mode 100644 .agents/skills/speckit-dev-workflow/SKILL.md delete mode 100644 .agents/skills/speckit-implement/SKILL.md delete mode 100644 .agents/skills/speckit-plan/SKILL.md delete mode 100644 .agents/skills/speckit-specify/SKILL.md delete mode 100644 .agents/skills/speckit-tasks/SKILL.md delete mode 100644 .agents/skills/speckit-taskstoissues/SKILL.md create mode 100644 .agents/tooling/generate_skill_mirrors.py create mode 100644 .claude/skills/archive/SKILL.md create mode 100644 .claude/skills/dev-workflow/SKILL.md create mode 100644 .claude/skills/dmir-compiler-analysis/SKILL.md create mode 100644 .claude/skills/dtvm-perf-profile/SKILL.md delete mode 100755 .specify/scripts/bash/check-prerequisites.sh delete mode 100755 .specify/scripts/bash/check-worktree.sh delete mode 100755 .specify/scripts/bash/common.sh delete mode 100755 .specify/scripts/bash/create-new-feature.sh delete mode 100755 .specify/scripts/bash/setup-plan.sh delete mode 100755 .specify/scripts/bash/update-agent-context.sh delete mode 100644 .specify/templates/agent-file-template.md delete mode 100644 .specify/templates/checklist-template.md delete mode 100644 .specify/templates/plan-template.md delete mode 100644 .specify/templates/spec-template.md delete mode 100644 .specify/templates/tasks-template.md rename {specs => docs}/_archive/2026-01/add-evmc-vm-interface-lib/design.md (100%) rename {specs => docs}/_archive/2026-01/add-evmc-vm-interface-lib/proposal.md (100%) rename {specs => docs}/_archive/2026-01/add-evmc-vm-interface-lib/specs/evmc-vm-interface/spec.md (100%) rename {specs => docs}/_archive/2026-01/add-evmc-vm-interface-lib/tasks.md (100%) rename {specs => docs}/_archive/2026-02/add-clz-opcode/proposal.md (100%) rename {specs => docs}/_archive/2026-02/add-clz-opcode/specs/evm-execution/spec.md (100%) rename {specs => docs}/_archive/2026-02/add-clz-opcode/specs/evm-jit/spec.md (100%) rename {specs => docs}/_archive/2026-02/add-clz-opcode/tasks.md (100%) rename {specs => docs}/_archive/2026-02/add-jit-suitability-checker/design.md (100%) rename {specs => docs}/_archive/2026-02/add-jit-suitability-checker/proposal.md (100%) rename {specs => docs}/_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md (100%) rename {specs => docs}/_archive/2026-02/add-jit-suitability-checker/tasks.md (100%) rename {specs => docs}/_archive/2026-03/add-evm-jit-fallback/design.md (100%) rename {specs => docs}/_archive/2026-03/add-evm-jit-fallback/proposal.md (100%) rename {specs => docs}/_archive/2026-03/add-evm-jit-fallback/specs/evm-execution/spec.md (100%) rename {specs => docs}/_archive/2026-03/add-evm-jit-fallback/specs/evm-jit-fallback/spec.md (100%) rename {specs => docs}/_archive/2026-03/add-evm-jit-fallback/tasks.md (100%) rename {openspec/changes => docs/_archive/2026-04}/update-evm-memory-block-precheck/design.md (100%) rename {openspec/changes => docs/_archive/2026-04}/update-evm-memory-block-precheck/proposal.md (96%) rename {openspec/changes => docs/_archive/2026-04}/update-evm-memory-block-precheck/specs/evm-jit/spec.md (100%) rename {openspec/changes => docs/_archive/2026-04}/update-evm-memory-block-precheck/tasks.md (100%) rename {specs => docs}/_archive/README.md (82%) rename {specs => docs}/architecture/README.md (100%) create mode 100644 docs/changes/README.md create mode 100644 docs/changes/template-light.md create mode 100644 docs/changes/template.md rename {specs => docs}/code-style/README.md (100%) rename {specs => docs}/data-model/README.md (100%) rename {specs => docs}/modules/README.md (100%) rename {specs => docs}/modules/action/data-model.md (100%) rename {specs => docs}/modules/action/spec.md (100%) rename {specs => docs}/modules/cli/data-model.md (100%) rename {specs => docs}/modules/cli/spec.md (100%) rename {specs => docs}/modules/common/data-model.md (100%) rename {specs => docs}/modules/common/spec.md (100%) rename {specs => docs}/modules/compiler/data-model.md (100%) rename {specs => docs}/modules/compiler/spec.md (97%) rename {specs => docs}/modules/evm/data-model.md (100%) rename {specs => docs}/modules/evm/spec.md (100%) rename {specs => docs}/modules/host/data-model.md (100%) rename {specs => docs}/modules/host/spec.md (100%) rename {specs => docs}/modules/platform/data-model.md (100%) rename {specs => docs}/modules/platform/spec.md (100%) rename {specs => docs}/modules/runtime/data-model.md (100%) rename {specs => docs}/modules/runtime/spec.md (100%) rename {specs => docs}/modules/rust-bindings/data-model.md (100%) rename {specs => docs}/modules/rust-bindings/spec.md (100%) rename {specs => docs}/modules/singlepass/data-model.md (100%) rename {specs => docs}/modules/singlepass/spec.md (99%) rename {specs => docs}/modules/tests/data-model.md (100%) rename {specs => docs}/modules/tests/spec.md (95%) rename {specs => docs}/modules/tools/spec.md (94%) rename {specs => docs}/modules/utils/data-model.md (100%) rename {specs => docs}/modules/utils/spec.md (100%) rename {specs => docs}/modules/vm-interface/data-model.md (100%) rename {specs => docs}/modules/vm-interface/spec.md (100%) rename {specs => docs}/testing/README.md (100%) delete mode 100644 specs/AGENTS.md delete mode 100644 specs/README.md delete mode 100644 specs/features/README.md diff --git a/.agents/skills/README.md b/.agents/skills/README.md index 17a26c877..52be2e060 100644 --- a/.agents/skills/README.md +++ b/.agents/skills/README.md @@ -1,113 +1,31 @@ -# Spec-Kit Sub-skills +# Agent Skills -This directory contains the complete set of Spec-Kit workflow sub-skills for specification-driven development. +Specialized skills for AI agents working on DTVM. -## Skill List - -| Skill | Name | Description | -|------|----------|----------| -| `speckit-specify` | Feature Spec Generation | Generate spec.md from natural language descriptions | -| `speckit-clarify` | Requirements Clarification | Batch questions to clarify ambiguities in specs | -| `speckit-plan` | Technical Design Planning | Generate design artifacts (research.md, data-model.md, plan.md, etc.) | -| `speckit-tasks` | Task List Generation | Generate executable tasks.md | -| `speckit-implement` | Code Implementation | Execute implementation according to the task list | -| `speckit-dev-workflow` | Full Development Workflow | Orchestrate all phases end-to-end | -| `speckit-constitution` | Project Principles | Define project development principles and constraints | -| `speckit-checklist` | Checklists | Generate domain-specific checklists | -| `speckit-analyze` | Project Analysis | Analyze project consistency | -| `speckit-taskstoissues` | Tasks to Issues | Convert tasks.md into issue tickets | -| `speckit-archive` | Feature Archival | Archive completed features after verifying preconditions | - -## Quick Start - -### Using Sub-skills Individually - -```bash -# 1. Create a feature spec -/skills/speckit-specify "Add user authentication" - -# 2. Clarify requirements (if ambiguities exist) -/skills/speckit-clarify - -# 3. Technical design -/skills/speckit-plan - -# 4. Generate task list -/skills/speckit-tasks - -# 5. Execute implementation -/skills/speckit-implement - -# 6. Archive completed features -/skills/speckit-archive -``` - -### Using the Full Workflow +**This directory is the single source of truth (SSOT) for all agent skills.** +`.claude/skills/` contains auto-generated mirrors — do not edit mirrors directly. +To regenerate mirrors after changes, run: ```bash -# Complete all steps in one go -/skills/speckit-dev-workflow "Add user authentication" +python3 .agents/tooling/generate_skill_mirrors.py ``` -### SDD Initialization for Existing Projects +## Available Skills -```bash -# Analyze the project and generate an SDD initialization plan (companion skill at claude/skills/speckit-ssot-sdd-init-plan) -/skills/speckit-ssot-sdd-init-plan -``` +| Skill | Description | +|-------|-------------| +| `dev-workflow` | End-to-end feature development: propose, plan, execute, verify, archive | +| `archive` | Archive completed change proposals to `docs/_archive/` | +| `dtvm-perf-profile` | Performance profiling with hardware counters | +| `dmir-compiler-analysis` | DMIR compiler analysis and cost model reference | ## Directory Structure -Copy these skills to the project's `.agents/skills/` directory: - ``` -project-root/ -└── .agents/ - └── skills/ - ├── speckit-specify/ - │ └── SKILL.md - ├── speckit-clarify/ - │ └── SKILL.md - ├── speckit-plan/ - │ └── SKILL.md - ├── speckit-tasks/ - │ └── SKILL.md - ├── speckit-implement/ - │ └── SKILL.md - ├── speckit-dev-workflow/ - │ └── SKILL.md - ├── speckit-constitution/ - │ └── SKILL.md - ├── speckit-checklist/ - │ └── SKILL.md - ├── speckit-analyze/ - │ └── SKILL.md - ├── speckit-taskstoissues/ - │ └── SKILL.md - └── speckit-archive/ - └── SKILL.md +.agents/skills/ +├── README.md +├── dev-workflow/SKILL.md +├── archive/SKILL.md +├── dtvm-perf-profile/SKILL.md +└── dmir-compiler-analysis/SKILL.md ``` - -## Skill Design Principles - -### English-First - -- Metadata (name, description) uses English for Claude Code recognition -- Content is in English for broader accessibility - -### Independent and Composable - -Each sub-skill is independent and can be: -- Invoked individually -- Combined sequentially -- Orchestrated within a workflow - -### Template and Script Dependencies - -These skills depend on the following project resources: - -- `.specify/scripts/bash/*.sh` - Helper scripts -- `.specify/templates/*.md` - Document templates -- `specs/` - SSOT directory structure - -Ensure these resources are in place before invoking these skills. diff --git a/.agents/skills/archive/SKILL.md b/.agents/skills/archive/SKILL.md new file mode 100644 index 000000000..ba6d779e9 --- /dev/null +++ b/.agents/skills/archive/SKILL.md @@ -0,0 +1,78 @@ +--- +name: archive +description: Archive completed change proposals from docs/changes/ to docs/_archive/ after verifying preconditions. +--- + +# Feature Archival + +Archive completed change proposals from `docs/changes/` to `docs/_archive//`. + +## When to Use + +- After a change is implemented, tested, reviewed, and merged +- As the final step of the `dev-workflow` skill + +## Preconditions + +All of the following must be true before archiving: + +| # | Condition | How to Verify | +|---|-----------|---------------| +| 1 | Implementation complete | All checklist items in the change doc are done | +| 2 | Build and tests pass | Run the project's build and test commands | +| 3 | Code review approved | PR has been approved | +| 4 | Branch merged | Feature branch merged into target branch | +| 5 | Module specs updated | Related specs in `docs/modules/` reflect any contract changes | + +If conditions are not met, report what is missing and suggest completing those first. + +## Steps + +### 1. Identify the Change + +If the user specifies a change, locate it. Otherwise, list changes in `docs/changes/` with status `Implemented` for the user to choose. + +### 2. Verify Preconditions + +Check each precondition: + +1. Read the change document and verify all checklist items are complete +2. Check git status: whether the branch has been merged (`git branch --merged`) +3. Check whether affected module specs were updated + +Present a summary: + +``` +Archive check: YYYY-MM-DD- + + Tasks: N/N complete + Branch: merged into main + Module specs: updated / needs sync + Tests/review: user confirmation required + +Proceed? +``` + +### 3. Execute + +After confirmation: + +1. Create `docs/_archive//` if it does not exist +2. Move the change directory: `docs/changes/YYYY-MM-DD-/` to `docs/_archive///` +3. Update the table in `docs/changes/README.md` (remove or mark the entry) +4. Add the entry to `docs/_archive/README.md` + +### 4. Cleanup (Optional) + +Ask the user: +- **Branch cleanup**: `git branch -d ` (if merged) +- **Worktree cleanup**: `git worktree remove ` (if used) + +## Batch Archival + +If multiple changes are ready, list them all and let the user select which to archive. + +## Notes + +- Archived specs are historical reference only and should not be modified +- If an archived change needs rework, create a new change proposal referencing the original diff --git a/.agents/skills/dev-workflow/SKILL.md b/.agents/skills/dev-workflow/SKILL.md new file mode 100644 index 000000000..555730015 --- /dev/null +++ b/.agents/skills/dev-workflow/SKILL.md @@ -0,0 +1,54 @@ +--- +name: dev-workflow +description: Feature development workflow. Propose a change, plan implementation, execute with gates, and verify. +--- + +# Development Workflow + +End-to-end workflow for implementing changes: propose, plan, execute, verify, and optionally archive. + +## Phase A - Propose + +1. Determine the change tier: + - **Full**: cross-module, architecture, new capabilities, breaking changes + - **Light**: single-module, well-scoped, limited blast radius + +2. Create a change document: + - Full tier: copy `docs/changes/template.md` to `docs/changes/YYYY-MM-DD-/README.md` + - Light tier: copy `docs/changes/template-light.md` to `docs/changes/YYYY-MM-DD-/README.md` + +3. Fill in the document and set status to `Proposed` + +4. Add the entry to the table in `docs/changes/README.md` + +## Phase B - Plan + +After the change proposal is accepted: + +1. Consult relevant module specs in `docs/modules//spec.md` +2. Identify affected files, contracts, and tests +3. Break the implementation into concrete, ordered steps +4. Present the plan for confirmation before proceeding + +## Phase C - Execute + +Implement with quality gates: + +1. **Build gate**: ensure the code compiles after each logical unit of work +2. **Test gate**: run existing tests after each unit; add new tests for new behavior +3. **Review gate**: check for determinism violations, memory safety, and spec compliance + +Mark each step complete as you go. + +## Phase D - Verify and Archive + +1. Run the full build and test suite +2. Update affected module specs in `docs/modules/` if contracts changed +3. Update the change document status to `Implemented` +4. Optionally use the `archive` skill to move the completed change to `docs/_archive/` + +## Notes + +- If the change is a simple bug fix or typo, skip to Phase C directly +- Always consult module specs before modifying code in unfamiliar areas +- When code conflicts with specs, code takes precedence, but update specs afterward diff --git a/.agents/skills/speckit-analyze/SKILL.md b/.agents/skills/speckit-analyze/SKILL.md deleted file mode 100644 index 5492e1838..000000000 --- a/.agents/skills/speckit-analyze/SKILL.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: speckit-analyze -description: Analyze project consistency, checking consistency and completeness between specs, designs, and implementations. ---- - -# Project Analysis - -Analyze project consistency, checking consistency and completeness between specs, designs, and implementations. - -## User Input - -Your input serves as the context. - -## Execution Steps - -### 1. Collect Project Artifacts - -Identify and collect all relevant project artifacts: -- Feature specs (`specs/features/*/spec.md`) -- Module specs (`specs/modules/*/spec.md`) -- Design documents (`research.md`, `data-model.md`, `plan.md`) -- Task lists (`tasks.md`) -- Implementation code - -### 2. Analyze Consistency - -Check the following consistency aspects: - -#### Spec to Design -- All requirements in the feature spec have corresponding entries in the design -- Data model matches entities defined in the spec -- API contracts are consistent with User Stories - -#### Design to Tasks -- All components in the design have corresponding implementation tasks -- Task dependencies are consistent with design dependencies -- Test tasks cover all design components - -#### Tasks to Implementation -- All tasks are completed (or correctly tracked) -- Implementation matches task descriptions -- Documentation is consistent with the implementation - -#### SSOT Consistency -- Feature specs correctly reference module SSOT -- No duplicate definitions -- Updates are correctly propagated to module specs - -### 3. Identify Issues - -Flag the following types of issues: -- Missing requirements or features -- Inconsistent naming or terminology -- Conflicting definitions -- Orphaned or unconnected components -- Outdated documentation - -### 4. Generate Report - -Generate an analysis report containing: - -#### Summary -- Overall consistency score -- Number and severity of issues - -#### Detailed Findings -- Description of each issue -- Affected files -- Suggested fixes - -#### Recommendations -- Issues to fix with priority -- Improvement suggestions - -### 5. Output Report - -Write the report to: -- Console output (summary) -- File (detailed report): `FEATURE_DIR/analysis/CONSISTENCY_REPORT.md` - -### 6. Report - -Report analysis results, including: -- Consistency score -- Number of issues found -- High-priority issues -- Suggested next steps diff --git a/.agents/skills/speckit-archive/SKILL.md b/.agents/skills/speckit-archive/SKILL.md deleted file mode 100644 index 8222fff1c..000000000 --- a/.agents/skills/speckit-archive/SKILL.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -name: speckit-archive -description: Feature archival. Archive completed features from specs/features/ to specs/_archive/ after verifying preconditions, and clean up branches and worktrees. ---- - -# Feature Archival - -Archive completed and merged feature specs from `specs/features/` to `specs/_archive//`, ensuring all preconditions are met before archival. - -## When to Use - -- After feature development, testing, and review are all complete, and the PR has been merged -- As the final step (Phase 8) of `speckit-dev-workflow` -- Periodic cleanup of completed but unarchived features - -## Archival Preconditions - -**All of the following conditions must be met before archival:** - -| # | Condition | Verification Method | -|---|------|---------| -| 1 | All tasks completed | All tasks in `tasks.md` are marked `[X]` | -| 2 | Tests/lint/build pass | Run the project's designated verification commands | -| 3 | Code review approved | PR has been approved | -| 4 | PR merged | Feature branch has been merged into the target branch | -| 5 | SSOT modules updated | Related modules in `specs/modules/` have synced changes | - -If conditions are not met, report the missing items to the user and suggest completing them first. - -## Execution Steps - -### Step 1: Identify Features to Archive - -If the user specifies a feature number or name, locate it directly. Otherwise, scan the `specs/features/` directory and list all features with their status for the user to choose from. - -### Step 2: Verify Preconditions - -Check the 5 preconditions one by one: - -1. Read `specs/features/-/tasks.md` and count completed vs. incomplete tasks -2. Check Git status: whether the feature branch has been merged (`git branch --merged`) -3. Check recent modifications to related files in `specs/modules/` (whether they were updated during feature development) - -Summarize the check results for the user: - -``` -Archival precondition check: - - -✅ Tasks completed: 15/15 (all complete) -✅ Branch merged: feature/- → main -⚠️ SSOT update: please confirm specs/modules/ has been synced -⬜ Tests/review: user confirmation required - -Proceed with archival? -``` - -### Step 3: Execute Archival - -After confirmation, execute: - -1. Create archive directory `specs/_archive//` (if it does not exist) -2. Move the feature directory: `specs/features/-/` → `specs/_archive//-/` - -### Step 4: Cleanup (Optional) - -Ask the user if cleanup is needed: - -- **Worktree cleanup**: `git worktree remove ` (if worktree mode was used) -- **Branch cleanup**: `git branch -d feature/-` (if the branch has been merged) - -### Step 5: Completion Report - -``` -Archival complete: - - -📦 Archived to: specs/_archive//-/ -🧹 Branch feature/- deleted (if cleanup was selected) -🧹 Worktree removed (if cleanup was selected) -``` - -## Batch Archival - -If there are multiple features to archive, batch operations are supported: - -1. List all features that meet the conditions -2. User selects features to archive (all or some) -3. Execute archival steps for each feature sequentially - -## Notes - -- Archived feature specs **should not be modified**; they serve as historical reference only -- If an archived feature needs rework, create a new feature proposal referencing the original spec -- The `_archive/` directory should be under version control as part of the project history diff --git a/.agents/skills/speckit-checklist/SKILL.md b/.agents/skills/speckit-checklist/SKILL.md deleted file mode 100644 index 20f4ba56d..000000000 --- a/.agents/skills/speckit-checklist/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: speckit-checklist -description: Generate checklists for specific domains to ensure quality control and completeness verification during development. ---- - -# Checklist Generation - -Generate checklists for specific domains to ensure quality control and completeness verification during development. - -## User Input - -Your input serves as the context. Specify the domain or feature for which to generate the checklist. - -## Execution Steps - -### 1. Determine Checklist Domain - -Analyze user input to determine: -- The domain of the checklist (e.g., UX, security, performance, accessibility) -- The project's specific context -- Any relevant standards or regulations - -### 2. Checklist Template - -Check if a relevant checklist template exists: -- `.specify/templates/checklist-template.md` -- Any domain-specific checklist templates - -### 3. Generate Checklist Items - -Generate appropriate checklist items for the identified domain. The checklist should include: - -#### Content Quality -- Content completeness and accuracy -- Clarity and conciseness -- Appropriate level of detail - -#### Functionality -- Feature completeness -- Edge case handling -- Error handling - -#### User Experience -- Usability -- Accessibility -- Performance -- Responsive design - -#### Technical Quality -- Code quality -- Test coverage -- Documentation completeness -- Security considerations - -#### Compliance -- Legal/regulatory requirements -- Organizational standards -- Industry best practices - -### 4. Create Checklist File - -Create the checklist file at the appropriate location: -- Feature checklist: `FEATURE_DIR/checklists/requirements.md` -- Domain checklist: `specs/checklists/DOMAIN.md` - -### 5. Format Checklist - -Use a consistent format: - -```markdown -# Checklist: [Name] - -## [Category] - -- [ ] Check item 1 -- [ ] Check item 2 -- [ ] Check item 3 - -## Notes - -[Any additional notes or context] -``` - -### 6. Report - -Report the location of the checklist file and the total number of items. diff --git a/.agents/skills/speckit-clarify/SKILL.md b/.agents/skills/speckit-clarify/SKILL.md deleted file mode 100644 index 3fc2d3e5d..000000000 --- a/.agents/skills/speckit-clarify/SKILL.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -name: speckit-clarify -description: Identify under-specified areas in the current feature spec by asking up to 5 highly targeted clarification questions, and encode the answers back into the spec. ---- - -# Requirements Clarification - -Identify and reduce ambiguities or missing decision points in the active feature spec, recording clarifications directly in the spec file. - -## User Input - -Your input serves as the context. - -## Handoff Points - -- **Build Technical Plan** → invoke `/speckit-plan`: "Create a plan for the spec. I am building with..." - -## Execution Steps - -### Goal - -Detect and reduce ambiguities or missing decision points in the active feature spec, and record clarifications directly in the spec file. - -**Note**: This clarification workflow is expected to run (and complete) before invoking `/speckit-plan`. If the user explicitly states they are skipping clarification (e.g., an exploratory spike), proceed but warn about increased downstream rework risk. - -### 1. Run Prerequisite Check - -Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from the repo root **once**. Parse the minimal JSON payload fields: -- `FEATURE_DIR` -- `FEATURE_SPEC` -- (Optionally capture `IMPL_PLAN`, `TASKS` for future chaining flows) - -If JSON parsing fails, abort and instruct the user to re-run `/speckit-specify` or verify the feature branch environment. - -### 2. Load and Analyze Current Spec - -Load the current spec file. Perform a structured ambiguity and coverage scan using the following taxonomy. For each category, flag its status: **Clear / Partial / Missing**. - -Generate an internal coverage map for prioritization (do not output the raw map unless no questions will be asked): - -**Feature Scope and Behavior**: -- Core user goals and success criteria -- Explicit out-of-scope declarations -- User role/persona differentiation - -**Domain and Data Model**: -- Entities, attributes, relationships -- Identity and uniqueness rules -- Lifecycle/state transitions -- Data volume/scale assumptions - -**Interaction and UX Flows**: -- Key user journeys/sequences -- Error/empty/loading states -- Accessibility or localization notes - -**Non-functional Quality Attributes**: -- Performance (latency, throughput targets) -- Scalability (horizontal/vertical, limits) -- Reliability and availability (uptime, recovery expectations) -- Observability (logging, metrics, tracing signals) -- Security and privacy (authN/Z, data protection, threat assumptions) -- Compliance/regulatory constraints (if applicable) - -**Integration and External Dependencies**: -- External services/APIs and their failure modes -- Data import/export formats -- Protocol/versioning assumptions - -**Edge Cases and Failure Handling**: -- Negative scenarios -- Rate limiting/throttling -- Conflict resolution (e.g., concurrent edits) - -**Constraints and Trade-offs**: -- Technical constraints (language, storage, hosting) -- Explicit trade-offs or rejected alternatives - -**Terminology and Consistency**: -- Canonical glossary terms -- Synonyms to avoid / deprecated terms - -**Completion Signals**: -- Acceptance criteria testability -- Measurable definition-of-done style metrics - -**Miscellaneous/Placeholders**: -- TODO markers / unresolved decisions -- Vague adjectives without quantification ("robust", "intuitive") - -For each category with **Partial** or **Missing** status, add a candidate question opportunity unless: -- The clarification would not materially change the implementation or verification strategy -- The information is best deferred to the planning phase (note internally) - -### 3. Generate Prioritized Question Queue - -Generate (internally) a prioritized queue of up to 5 candidate clarification questions. **Do not output all questions at once**. - -Apply these constraints: -- Maximum 5 questions for the entire session -- Each question must be answerable by: - - Short multiple-choice (2-5 distinct, mutually exclusive options), or - - A single word/phrase answer (explicitly constrained: "answer in <=5 words") -- Only include questions whose answers materially affect architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance verification -- Ensure balanced category coverage: try to cover the highest-impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) remains unresolved -- Exclude already-answered questions, trivial style preferences, or planning-level execution details (unless they block correctness) -- Prioritize clarifications that reduce downstream rework risk or prevent inconsistent acceptance tests -- If more than 5 categories remain unresolved, select the top 5 by (impact × uncertainty) heuristic - -### 4. Sequential Questioning Loop (Interactive) - -- Ask exactly one question at a time -- For **multiple-choice questions**: - - **Analyze all options** and determine the **most suitable option** based on: - - Best practices for the project type - - Common patterns in similar implementations - - Risk reduction (security, performance, maintainability) - - Alignment with any explicit project goals or constraints visible in the spec - - Highlight your **recommended option** at the top with clear reasoning (1-2 sentences explaining why it is the best choice) - - Format as: `**Recommended:** [X] - ` - - Then present all options as a Markdown table - - After the table add: `You can reply with the option letter (e.g. "A"), accept the recommended option by saying "yes" or "recommended", or provide your own short answer.` -- For **short-answer style** (no meaningful discrete options): - - Provide your **suggested answer** based on best practices and context - - Format as: `**Suggested answer:** - ` - - Then output: `Format: short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.` -- After the user answers: - - If the user replies "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer - - Otherwise, validate the answer maps to an option or meets the <=5-word constraint - - If ambiguous, ask for quick disambiguation (still counts as the same question; do not advance) - - Once satisfactory, record it in working memory (do not write to disk yet) and move to the next queued question -- **Stop asking further questions** when: - - All critical ambiguities resolve early (remaining queued items become unnecessary), or - - The user signals completion ("done", "good", "no more", etc.), or - - You reach 5 questions -- Never reveal future queued questions ahead of time -- If no valid questions exist at the start, immediately report that no critical ambiguities were found - -### 5. Integration After Each Accepted Answer (Incremental Update Approach) - -- Maintain an in-memory representation of the spec (loaded once at start) plus the original file content -- For the first integrated answer in this session: - - Ensure a `## Clarifications` section exists (if missing, create it after the spec template's top-level context/overview section) - - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today -- Append a bullet line immediately after acceptance: `- Q: → A: ` -- Then immediately apply the clarification to the most appropriate section: - - Feature ambiguity → update or add bullet points in functional requirements - - User interaction/role differentiation → update User Stories or role subsection (if present) with clarified roles, constraints, or scenarios - - Data shape/entity → update data model (add fields, types, relationships) preserving ordering; document added constraints concisely - - Non-functional constraints → add/modify measurable criteria in non-functional/quality attributes section (convert vague adjectives to metrics or explicit goals) - - Edge cases/negative flows → add new bullet points under edge cases/error handling (or create such subsection if the template provides a placeholder) - - Terminology conflicts → normalize terms throughout the spec; preserve original terms only if necessary by adding `(formerly referred to as "X")` once -- If a clarification invalidates an earlier ambiguous statement, replace that statement rather than duplicating; do not leave outdated contradictory text -- Save the spec file after each integration to minimize risk of context loss (atomic overwrite) -- Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact -- Keep each inserted clarification minimal and testable (avoid narrative drift) - -### 6. Validation (After Each Write Plus Final Pass) - -- The clarification session contains exactly one bullet per accepted answer (no duplicates) -- Total questions asked (accepted) ≤ 5 -- Updated sections have no residual ambiguous placeholders that the new answer was intended to resolve -- No contradictory earlier statements remain (scan for now-invalid alternative choices that were removed) -- Markdown structure is valid; only new headings allowed: `## Clarifications`, `### Session YYYY-MM-DD` -- Terminology consistency: use the same canonical terms across all updated sections - -### 7. Write Updated Spec Back to `FEATURE_SPEC` - -### 8. Report Completion (After Questioning Loop Ends or Early Termination) - -- Number of questions asked and answered -- Path to the updated spec -- Sections touched (list names) -- Coverage summary table listing each taxonomy category and its status: - - **Resolved** (was Partial/Missing and has been addressed) - - **Deferred** (exceeded question quota or better suited for planning) - - **Clear** (already sufficient) - - **Outstanding** (still Partial/Missing but low impact) -- If any Outstanding or Deferred items exist, suggest whether to proceed to `speckit-plan` or re-run `speckit-clarify` after planning -- Suggested next command - -## Behavioral Rules - -- If no meaningful ambiguities are found (or all potential questions are low-impact), respond: "No critical ambiguities warranting formal clarification detected." and suggest proceeding -- If the spec file is missing, instruct the user to run `speckit-specify` first (do not create a new spec here) -- Never exceed 5 total questions asked (disambiguation retries for a single question do not count as a new question) -- Avoid speculative tech-stack questions unless the lack of a tech stack blocks feature clarity -- Respect user early-termination signals ("stop", "done", "proceed", etc.) -- If no questions were asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest moving forward -- If quota is reached while high-impact categories remain unresolved, explicitly flag them under Deferred with rationale diff --git a/.agents/skills/speckit-constitution/SKILL.md b/.agents/skills/speckit-constitution/SKILL.md deleted file mode 100644 index cf1a05be7..000000000 --- a/.agents/skills/speckit-constitution/SKILL.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: speckit-constitution -description: Define project development principles and constraints. Generate or update the project constitution document to provide guiding principles for all subsequent development activities. ---- - -# Project Principles - -Define project development principles and constraints to provide guiding principles for all subsequent development activities. - -## User Input - -Your input serves as the context. - -## Execution Steps - -### 1. Check Existing Constitution Document - -Check if the following files exist: -- `.specify/memory/constitution.md` -- `specs/constitution.md` -- `CONSTITUTION.md` - -If one exists, read its content and prepare for updates. - -### 2. Gather Project Context - -Analyze the project to determine appropriate constraints: -- Programming languages and frameworks -- Target platforms and deployment environments -- Performance requirements -- Security and compliance requirements -- Team size and collaboration patterns - -### 3. Generate Constitution Document Structure - -Create or update the constitution document with the following sections: - -#### Project Vision -- Project purpose and goals -- Target users/use cases -- Definition of success - -#### Technical Constraints -- Allowed programming languages -- Allowed frameworks and libraries -- Architecture pattern requirements -- Platform requirements - -#### Quality Standards -- Code style guides -- Test coverage requirements -- Documentation standards -- Performance benchmarks - -#### Development Process -- Git workflow -- Code review requirements -- CI/CD requirements -- Release process - -#### Security and Compliance -- Data protection requirements -- Access control standards -- Audit requirements -- Legal compliance considerations - -#### Team Collaboration -- Communication protocols -- Decision-making process -- Dispute resolution -- Knowledge sharing - -### 4. Write Document - -Write the constitution document to `.specify/memory/constitution.md`. - -### 5. Validate - -Confirm the document includes: -- All required sections -- Clear, actionable constraints -- Alignment with project goals -- Team consensus (if applicable) - -### 6. Report - -Report the location of the constitution document and any critical decisions requiring human review. diff --git a/.agents/skills/speckit-dev-workflow/SKILL.md b/.agents/skills/speckit-dev-workflow/SKILL.md deleted file mode 100644 index 45cd17a55..000000000 --- a/.agents/skills/speckit-dev-workflow/SKILL.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: speckit-dev-workflow -description: Full Spec-Kit feature development workflow. From natural language description to implementation completion, batch requirements clarification and planning first, then push implementation through in one pass, and finally sync SSOT, roadmap, and documentation. ---- - -# Full Development Workflow - -Starting from a single requirements description, proceed through batch clarification, planning confirmation, push through to implementation completion, and sync all related documentation. - -## Workflow Overview - -``` -Phase 1: Specify — Generate feature spec draft (invoke /speckit-specify) -Phase 2: Clarify — Batch ambiguity questions, await user confirmation (invoke /speckit-clarify) -Phase 3: Plan — Generate technical design artifacts (invoke /speckit-plan) -Phase 4: Tasks — Generate executable task list (invoke /speckit-tasks) -Phase 5: Implement — Execute implementation by tasks (invoke /speckit-implement) -Phase 6: Doc Sync — Sync SSOT / roadmap / README / AGENTS.md -Phase 7: Validate — lint + build + test verification -``` - -**Key Checkpoints**: -- Phase 2 presents all ambiguity questions at once. **After the user answers, proceed immediately to Phase 3 without additional confirmation** -- Phase 4 presents a task summary to the user for confirmation. **Implementation begins only after confirmation** -- Workflow ends after Phase 7 passes completely - -Refer to the corresponding standalone skill for detailed execution logic of each phase; this workflow handles orchestration and checkpoint control. - -## User Input - -Your input serves as the feature description. - -## Execution Steps - -### Phase 1 — Specify - -Invoke `create-new-feature.sh` to create the feature directory scaffold. The script **automatically generates the `spec.md` template file**. - -> ⚠️ **`spec.md` has already been created by the script**. When filling in spec content later, you must use edit tools. **Do not use file creation tools** (this will cause a "File already exists" error). - -### Phase 2 — Clarify (Key Differentiator of This Workflow) - -**Standard speckit-clarify behavior allows multi-round follow-ups; this workflow requires batch questioning in one pass.** - -Scan spec.md, identify uncertainties that affect architecture or implementation paths (tech stack, process model, data model, API contracts, build/release, scope boundaries, etc.), and present **all questions at once** (up to 5), each with 2-4 options and a recommended default. Wait for the user to answer all before continuing. - -After answers are confirmed: -1. Write back to the `## Clarifications` section of `spec.md` -2. Sync key constraints to corresponding FR and Assumptions -3. **Proceed immediately to Phase 3 (Plan)** without waiting for further instructions - -### Phase 3 — Plan (Artifact Checklist) - -Follow the `speckit-plan` skill. **The following artifacts must all be generated in the feature directory**: - -| File | Description | -|------|------| -| `research.md` | Key technical decisions (Decision / Rationale / Alternatives considered) | -| `data-model.md` | New entities, DTO types, field descriptions, state machine enums | -| `contracts/` | API endpoint OpenAPI or interface descriptions (if new endpoints exist) | -| `quickstart.md` | Developer quickstart: setup steps, end-to-end flow examples, API call examples | -| `plan.md` | Architecture overview, phase breakdown, key pseudocode | - -After all artifacts are generated, **proceed immediately to Phase 4** without waiting for confirmation. - -### Phase 4 — Tasks - -After generating `tasks.md`, present a task summary (task count, phase overview) to the user. **Begin Phase 5 implementation only after user confirmation**. - -### Phase 5 — Implement - -Execute implementation according to the task list, marking each task as `[X]` upon completion. - -### Phase 6 — Doc Sync - -Review after implementation is complete. **Modify only if there are changes**: - -| File | When to Modify | -|------|---------| -| `specs/modules/*/contracts/interfaces.md` | New/changed API endpoints, SSE contracts, error codes | -| `specs/modules/*/data-model.md` | New entities or DTO types | -| `specs/mvp-roadmap.md` | Change feature status from `🚧 In Progress` to `✅ Completed` | -| `README.md` | New user-facing commands, URLs, or installation step changes | -| `AGENTS.md` | New dev commands, Agent-callable APIs, common error codes | - -**When unsure whether modification is needed**: state the rationale explicitly; do not force modifications. - -### Phase 7 — Validate - -Run lint / test / build commands per project conventions sequentially. If any fail, **fix in place** and re-run. Do not skip. Workflow ends after all pass. - -## Completion Checklist - -- [ ] `spec.md` contains FR numbering and `## Clarifications` section -- [ ] `research.md` generated with key technical decisions and alternatives -- [ ] `data-model.md` generated with new entities, DTO types, state machine enums -- [ ] `contracts/` generated (if new API endpoints exist) -- [ ] `quickstart.md` generated with setup steps and end-to-end flow examples -- [ ] `plan.md` generated with architecture description and phased path -- [ ] All implementation tasks completed -- [ ] Affected `specs/modules/` SSOT updated -- [ ] `specs/mvp-roadmap.md` status updated -- [ ] lint / test / build verification all passed diff --git a/.agents/skills/speckit-implement/SKILL.md b/.agents/skills/speckit-implement/SKILL.md deleted file mode 100644 index aad84ed93..000000000 --- a/.agents/skills/speckit-implement/SKILL.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -name: speckit-implement -description: Execute the implementation plan, processing and executing all tasks defined in tasks.md. ---- - -# Code Implementation - -Execute the implementation plan, processing and executing all tasks defined in tasks.md. - -## User Input - -Your input serves as the context. - -## Execution Steps - -### 1. Setup - -Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from the repo root and parse: -- FEATURE_DIR -- AVAILABLE_DOCS list - -All paths must be absolute paths. - -### 2. Checklist Status (if FEATURE_DIR/checklists/ exists) - -- Scan all checklist files in the checklists/ directory -- For each checklist, count: - - Total items: all lines matching `- [ ]` or `- [X]` or `- [x]` - - Completed items: lines matching `- [X]` or `- [x]` - - Incomplete items: lines matching `- [ ]` -- Create status table: - -```text -| Checklist | Total | Completed | Incomplete | Status | -|-----------|-------|-----------|------------|--------| -| ux.md | 12 | 12 | 0 | ✓ PASS | -| test.md | 8 | 5 | 3 | ✗ FAIL | -``` - -- Determine overall status: - - **PASS**: all checklists have 0 incomplete items - - **FAIL**: one or more checklists have incomplete items - -- **If any checklist is incomplete**: - - Display the table with incomplete item counts - - **Stop** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)" - - Wait for user response before continuing - - If the user says "no" or "wait" or "stop", halt execution - - If the user says "yes" or "proceed" or "continue", continue to step 3 - -- **If all checklists are complete**: - - Display the table showing all checklists passed - - Automatically continue to step 3 - -### 3. Load and Analyze Implementation Context - -- **Required**: read tasks.md for the full task list and execution plan -- **Required**: read plan.md for tech stack, architecture, and file structure -- **If exists**: read data-model.md for entities and relationships -- **If exists**: read contracts/ for API specifications and test requirements -- **If exists**: read research.md for technical decisions and constraints -- **If exists**: read quickstart.md for integration scenarios - -### 4. Project Setup Verification - -- **Required**: create/verify ignore files based on actual project setup - -**Detection and creation logic**: -- Check if the repo is a git repository (if so, create/verify .gitignore) -- Create appropriate ignore files based on the project's technologies - -### 5. Parse tasks.md Structure and Extract - -- Task phases: Setup, Tests, Core, Integration, Polish -- Task dependencies: sequential vs. parallel execution rules -- Task details: ID, description, file paths, parallel marker [P] -- Execution flow: order and dependency requirements - -### 6. Execute Implementation by Task Plan - -- **Execute phase by phase**: complete each phase before moving to the next -- **Respect dependencies**: run sequential tasks in order; parallel tasks [P] can run together -- **Follow TDD methodology**: execute test tasks before their corresponding implementation tasks -- **File-based coordination**: tasks affecting the same file must run sequentially -- **Validation checkpoints**: verify each phase completion before continuing - -### 7. Implementation Execution Rules - -- **Setup first**: initialize project structure, dependencies, configuration -- **Tests first**: write tests for contracts, entities, and integration scenarios if needed -- **Core development**: implement models, services, CLI commands, endpoints -- **Integration work**: database connections, middleware, logging, external services -- **Polish and verification**: unit tests, performance optimization, documentation - -### 8. Progress Tracking and Error Handling - -- Report progress after each completed task -- If any non-parallel task fails, halt execution -- For parallel tasks [P], continue successful tasks and report failed ones -- Provide clear error messages and debugging context -- If implementation cannot continue, suggest next steps -- **Important**: for completed tasks, ensure the task is marked as [X] in the tasks file - -### 9. Completion Verification - -- Verify all required tasks are completed -- Check that implemented features match the original spec -- Verify tests pass and coverage meets requirements -- Confirm implementation follows the technical plan -- Report final status and a summary of completed work - -**Note**: this command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `speckit-tasks` first to regenerate the task list. diff --git a/.agents/skills/speckit-plan/SKILL.md b/.agents/skills/speckit-plan/SKILL.md deleted file mode 100644 index 661bcb3a7..000000000 --- a/.agents/skills/speckit-plan/SKILL.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -name: speckit-plan -description: Execute the implementation planning workflow, generating design artifacts (research.md, data-model.md, contracts/, quickstart.md, plan.md) using plan templates. ---- - -# Technical Design Planning - -Execute the implementation planning workflow and generate design artifacts. - -## User Input - -Your input serves as the context. - -## Handoff Points - -- **Create Tasks** → invoke `/speckit-tasks`: "Break the plan into tasks" (send: true) -- **Create Checklist** → invoke `/speckit-checklist`: "Create a checklist for the following domain..." - -## Execution Steps - -### 1. Setup - -Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse the JSON for: -- FEATURE_SPEC -- IMPL_PLAN -- SPECS_DIR -- BRANCH - -### 2. Load Context - -Read: -- FEATURE_SPEC (feature spec) -- `.specify/memory/constitution.md` (project principles) -- IMPL_PLAN template (already copied) - -### 3. Execute Planning Workflow - -Follow the IMPL_PLAN template structure: -- Fill in the technical context (mark unknowns as "NEEDS CLARIFICATION") -- Fill in the principles check section from the constitution -- Evaluate gate criteria (error if violations are unproven) -- **Phase 0**: generate research.md (resolve all NEEDS CLARIFICATION) -- **Phase 1**: generate data-model.md, contracts/, quickstart.md -- **Phase 1**: run agent script to update agent context -- Re-evaluate principles check after design - -### 4. Stop and Report - -The command ends after Phase 2 planning. Report the branch, IMPL_PLAN path, and generated artifacts. - -## Phase Details - -### Phase 0: Outline and Research - -1. Extract unknowns from technical context: - - Each NEEDS CLARIFICATION → research task - - Each dependency → best practices task - - Each integration → patterns task - -2. Generate and dispatch research agents - -3. Consolidate findings in `research.md` using the format: - - Decision: [what was chosen] - - Rationale: [why it was chosen] - - Alternatives considered: [what else was evaluated] - -**Output**: research.md with all NEEDS CLARIFICATION resolved - -### Phase 1: Design and Contracts - -**Prerequisite**: `research.md` complete - -1. Extract entities from the feature spec → `data-model.md`: - - Entity names, fields, relationships - - Validation rules from requirements - - State transitions (if applicable) - -2. Generate API contracts from functional requirements: - - Each user action → endpoint - - Use standard REST/GraphQL patterns - - Output OpenAPI/GraphQL schemas to `/contracts/` - -3. Agent context update: - - Run `.specify/scripts/bash/update-agent-context.sh cursor-agent` - - The script detects which AI agent is being used - - Update the corresponding agent-specific context file - - Only add new technologies from the current plan - - Preserve manual additions between markers - -**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific files - -## Key Rules - -- Use absolute paths -- Error on gate failure or unresolved clarifications diff --git a/.agents/skills/speckit-specify/SKILL.md b/.agents/skills/speckit-specify/SKILL.md deleted file mode 100644 index 770ab540b..000000000 --- a/.agents/skills/speckit-specify/SKILL.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -name: speckit-specify -description: Create or update a feature specification from a natural language description. Generate feature directory structure, spec.md template, with smart numbering and branch management support. ---- - -# Feature Spec Generation - -Create or update a feature specification (spec.md) from a natural language feature description. - -## User Input - -Your input (the feature description in the conversation) serves as the feature description. - -## Handoff Points - -- **Build Technical Plan** → invoke `/speckit-plan`: "Create a plan for the spec. I am building with..." -- **Clarify Spec Requirements** → invoke `/speckit-clarify`: "Clarify specification requirements" (send: true) - -## Execution Steps - -### 1. Generate a Concise Short Name - -Analyze the feature description and extract the most meaningful keywords: - -- Use a 2-4 word short name to capture the feature essence -- Use action-noun format (e.g., "add-user-auth", "fix-payment-bug") -- Preserve technical terms and abbreviations (OAuth2, API, JWT, etc.) -- Keep it concise but sufficiently descriptive -- Feature directory will be created as `specs/features/NNN-short-name` (e.g., `specs/features/001-user-auth`) -- Branch references use the `feature/` prefix (e.g., `feature/001-user-auth`) — note: branches are not created by default - -**Examples**: -- "I want to add user authentication" → feature: `001-user-auth` -- "Implement OAuth2 integration for the API" → feature: `002-oauth2-api-integration` -- "Create a dashboard for analytics" → feature: `003-analytics-dashboard` -- "Fix payment processing timeout bug" → feature: `004-fix-payment-timeout` - -### 2. Initialize Feature Spec Directory - -**a. Determine numbering source** (global max strategy): -- Existing feature directories: `specs/features/[0-9]+-*` -- Existing local/remote git feature branches (if git is available) -- Use the highest number + 1 as the next feature number - -**b. Use `create-new-feature.sh` to create the feature scaffold**: -- Default mode (recommended): do not switch branches, only create `specs/features/NNN-short-name/` -- Optional: add `--switch-branch` or `--worktree` only when explicitly requested -- Example (default): - ```bash - .specify/scripts/bash/create-new-feature.sh --json --number 5 --short-name "user-auth" "Add user authentication" - ``` -- Example (with branch): - ```bash - .specify/scripts/bash/create-new-feature.sh --json --switch-branch --number 5 --short-name "user-auth" "Add user authentication" - ``` -- Example (worktree): - ```bash - .specify/scripts/bash/create-new-feature.sh --json --worktree --number 5 --short-name "user-auth" "Add user authentication" - ``` - -**c. Parse the script's JSON output**: -- `FEATURE_DIR` -- `SPEC_FILE` -- `BRANCH_NAME` (if created) -- `WORKTREE_PATH` (if worktree mode) - -**Important**: -- This repo defaults to a single-branch workflow; branch creation is not required -- Numbering is based on the global max feature index, not the short-name local index -- This script must be run exactly once - -### 3. Load Spec Template - -Load `.specify/templates/spec-template.md` to understand the required sections. - -### 4. Execution Flow - -1. **Parse input**: get the feature description from the conversation - - If empty: error "No feature description provided" - -2. **Extract key concepts**: identify from the description - - Actors - - Actions - - Data - - Constraints - -3. **For unclear aspects**: - - Make reasonable assumptions based on context and industry standards - - Only flag `[NEEDS CLARIFICATION: specific question]` when: - - The choice significantly affects feature scope or user experience - - Multiple reasonable interpretations exist with different implications - - No reasonable default value exists - - **Limit**: at most 3 `[NEEDS CLARIFICATION]` markers - - Prioritize by impact: scope > security/privacy > UX > technical details - -4. **Fill in user scenarios and test sections** - - If user flows cannot be determined: error "Cannot determine user scenarios" - -5. **Generate functional requirements** - - Each requirement must be testable - - Use reasonable defaults for unspecified details (document in the assumptions section) - -6. **Define success criteria** - - Create measurable, technology-agnostic outcomes - - Include quantitative metrics (time, performance, count) and qualitative measures (user satisfaction, task completion rate) - - Each criterion must be verifiable without implementation details - -7. **Identify key entities** (if data is involved) - -8. **Return**: SUCCESS (spec is ready for planning) - -### 5. Write Spec to SPEC_FILE - -Use the template structure, replacing placeholders with specific details derived from the feature description, while preserving section order and headings. - -### 6. Spec Quality Validation - -**a. Create spec quality checklist**: -Create checklist file at `FEATURE_DIR/checklists/requirements.md` - -**b. Run validation checks**: -Validate the spec against each checklist item - -**c. Handle validation results**: -- **If all items pass**: mark checklist as complete -- **If items fail** (excluding `[NEEDS CLARIFICATION]`): update spec and re-validate -- **If `[NEEDS CLARIFICATION]` markers remain**: present options to the user - -### 7. Report Completion - -Return feature ID, spec file path, checklist results, and readiness for the next phase (`/speckit-clarify` or `/speckit-plan`). - -**Note**: by default, the script does not create or switch branches. Spec files are created in `specs/features/` on the current branch. Use `--switch-branch` or `--worktree` flags to create branches. - -## General Guidelines - -### Quick Guide - -- Focus on **what the user needs** and **why** -- Avoid **how to implement** (no tech stack, API, code structure) -- Write for business stakeholders, not developers -- Do not create any checklists embedded in the spec - -### Section Requirements - -- **Required sections**: must be completed for every feature -- **Optional sections**: include only when relevant -- When a section is not applicable, remove it entirely (do not leave as "N/A") - -### AI Generation Guidelines - -When creating specs: - -1. **Make reasonable assumptions**: use context, industry standards, and common patterns to fill gaps -2. **Document assumptions**: record reasonable defaults in the assumptions section -3. **Limit clarifications**: at most 3 `[NEEDS CLARIFICATION]` markers -4. **Prioritize clarifications**: scope > security/privacy > UX > technical details -5. **Think like a tester**: every vague requirement should fail the "testable and unambiguous" checklist item - -**Reasonable default examples** (do not ask about these): -- Data retention: industry-standard domain practices -- Performance targets: standard web/mobile app expectations unless stated otherwise -- Error handling: user-friendly messages with appropriate fallbacks -- Authentication method: standard session or OAuth2 for web apps -- Integration pattern: RESTful API unless stated otherwise - -### Success Criteria Guidelines - -Success criteria must be: - -1. **Measurable**: include specific metrics (time, percentages, counts, ratios) -2. **Technology-agnostic**: do not mention frameworks, languages, databases, or tools -3. **User-centric**: describe outcomes from the user/business perspective, not system internals -4. **Verifiable**: can be tested/verified without knowing implementation details - -**Good examples**: -- "Users can complete checkout within 3 minutes" -- "System supports 10,000 concurrent users" -- "95% of searches return results within 1 second" -- "Task completion rate improves by 40%" - -**Bad examples** (implementation-centric): -- "API response time under 200ms" (too technical) -- "Database can handle 1000 TPS" (implementation detail) -- "React components render efficiently" (framework-specific) -- "Redis cache hit rate exceeds 80%" (technology-specific) diff --git a/.agents/skills/speckit-tasks/SKILL.md b/.agents/skills/speckit-tasks/SKILL.md deleted file mode 100644 index 9fa32e450..000000000 --- a/.agents/skills/speckit-tasks/SKILL.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -name: speckit-tasks -description: Generate an actionable, dependency-ordered tasks.md task list based on available design artifacts. ---- - -# Task List Generation - -Generate an actionable, dependency-ordered tasks.md based on available design artifacts. - -## User Input - -Your input serves as the context. - -## Handoff Points - -- **Analyze For Consistency** → invoke `/speckit-analyze`: "Run a project analysis for consistency" (send: true) -- **Implement Project** → invoke `/speckit-implement`: "Start the implementation in phases" (send: true) - -## Execution Steps - -### 1. Setup - -Run `.specify/scripts/bash/check-prerequisites.sh --json` from the repo root and parse: -- FEATURE_DIR -- AVAILABLE_DOCS list - -All paths must be absolute paths. - -### 2. Load Design Documents - -Read from FEATURE_DIR: - -**Required**: -- plan.md (tech stack, libraries, structure) -- spec.md (User Stories and their priorities) - -**Optional**: -- data-model.md (entities) -- contracts/ (API endpoints) -- research.md (decisions) -- quickstart.md (test scenarios) - -Note: not all projects will have all documents. Generate tasks based on available content. - -### 3. Execute Task Generation Workflow - -- Load plan.md and extract tech stack, libraries, project structure -- Load spec.md and extract User Stories and their priorities (P1, P2, P3, etc.) -- If data-model.md exists: extract entities and map to User Stories -- If contracts/ exists: map endpoints to User Stories -- If research.md exists: extract decisions for setup tasks -- Generate tasks organized by User Story (see task generation rules below) -- Generate a dependency graph showing User Story completion order -- Create parallel execution examples for each User Story -- Validate task completeness (each User Story has all required tasks, independently testable) - -### 4. Generate tasks.md - -Use `.specify/templates/tasks-template.md` as the structure, filling in: -- Correct feature name from plan.md -- Phase 1: setup tasks (project initialization) -- Phase 2: foundation tasks (blocking prerequisites for all User Stories) -- Phase 3+: one phase per User Story (ordered by priority from spec.md) -- Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks -- Final phase: polish and cross-cutting concerns -- All tasks must follow the strict checklist format (see task generation rules below) -- Clear file paths for each task -- Dependency section showing story completion order -- Parallel execution examples for each story -- Implementation strategy section (MVP-first, incremental delivery) - -### 5. Report - -Output the generated tasks.md path and summary: -- Total task count -- Task count per User Story -- Identified parallelization opportunities -- Independent test criteria per story -- Suggested MVP scope (typically just User Story 1) -- Format validation: confirm all tasks follow the checklist format (checkbox, ID, labels, file paths) - -tasks.md should be immediately executable — each task must be specific enough for an LLM to complete without additional context. - -## Task Generation Rules - -**Key**: tasks must be organized by User Story to enable independent implementation and testing. - -**Tests are optional**: only generate test tasks when explicitly requested in the feature spec or when the user requests a TDD approach. - -### Checklist Format (Required) - -Each task must strictly follow this format: - -```text -- [ ] [TaskID] [P?] [Story?] Description with file path -``` - -**Format components**: - -1. **Checkbox**: always start with `- [ ]` (markdown checkbox) -2. **Task ID**: sequential number in execution order (T001, T002, T003...) -3. **[P] marker**: include only when the task is parallelizable (different files, no dependency on incomplete tasks) -4. **[Story] label**: required only for User Story phase tasks - - Format: [US1], [US2], [US3], etc. (maps to User Stories in spec.md) - - Setup phase: no story label - - Foundation phase: no story label - - User Story phases: must have story label - - Polish phase: no story label -5. **Description**: clear action with precise file paths - -**Examples**: -- ✅ Correct: `- [ ] T001 Create project structure per implementation plan` -- ✅ Correct: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py` -- ✅ Correct: `- [ ] T012 [P] [US1] Create User model in src/models/user.py` -- ✅ Correct: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py` -- ❌ Wrong: `- [ ] Create User model` (missing ID and story label) -- ❌ Wrong: `T001 [US1] Create model` (missing checkbox) -- ❌ Wrong: `- [ ] [US1] Create User model` (missing task ID) -- ❌ Wrong: `- [ ] T001 [US1] Create model` (missing file path) - -### Task Organization - -1. **From User Stories (spec.md)** - primary organization: - - Each User Story (P1, P2, P3...) has its own phase - - Map all related components to their story: - - Models needed for that story - - Services needed for that story - - Endpoints/UI needed for that story - - If tests requested: story-specific tests - - Mark story dependencies (most stories should be independent) - -2. **From contracts**: - - Map each contract/endpoint → to the User Story it serves - - If tests requested: each contract → contract test task [P] before implementation in that story phase - -3. **From data model**: - - Map each entity to the User Story that needs it - - If an entity serves multiple stories: place in the earliest story or setup phase - - Relationships → service layer tasks in the corresponding story phase - -4. **From setup/infrastructure**: - - Shared infrastructure → setup phase (Phase 1) - - Foundation/blocking tasks → foundation phase (Phase 2) - - Story-specific setup → within that story phase - -### Phase Structure - -- **Phase 1**: Setup (project initialization) -- **Phase 2**: Foundation (blocking prerequisites — must complete before User Stories) -- **Phase 3+**: User Stories in priority order (P1, P2, P3...) - - Within each story: tests (if requested) → models → services → endpoints → integration - - Each phase should be a complete, independently testable increment -- **Final phase**: Polish and cross-cutting concerns diff --git a/.agents/skills/speckit-taskstoissues/SKILL.md b/.agents/skills/speckit-taskstoissues/SKILL.md deleted file mode 100644 index 43192fca0..000000000 --- a/.agents/skills/speckit-taskstoissues/SKILL.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -name: speckit-taskstoissues -description: Convert tasks in tasks.md into issue tickets, supporting platforms such as GitHub and GitLab. ---- - -# Tasks to Issues - -Convert tasks in tasks.md into issue tickets, supporting platforms such as GitHub and GitLab. - -## User Input - -Your input serves as the context. - -## Execution Steps - -### 1. Load Task File - -Load the task list from `FEATURE_DIR/tasks.md`. - -### 2. Parse Tasks - -Parse the task file and extract: -- Task ID -- Task description -- Task labels (e.g., [US1], [P]) -- File paths -- Dependencies - -### 3. Determine Target Platform - -Determine the target platform for issue creation: -- GitHub (via `gh` CLI or API) -- GitLab (via `glab` CLI or API) -- Other platforms (generate a generic format) - -### 4. Convert Tasks to Issues - -Create an issue for each task, including: - -#### Issue Title -- Task ID + short description -- Remove file paths (place in the body instead) - -#### Issue Body -- Full task description -- File paths -- Related User Story (if any) -- Dependent tasks (if any) -- Acceptance criteria (extracted from tasks.md) - -#### Labels -- Priority (inferred from the task) -- User Story label -- Phase label (Setup, Core, Integration, etc.) -- Technical labels (inferred from file paths) - -### 5. Manage Issue Dependencies - -- Create issues in order -- Set dependencies using issue references -- Consider the platform's dependency management features - -### 6. Create Issues - -Create issues using the appropriate method: - -**GitHub (via CLI)**: -```bash -gh issue create --title "TITLE" --body "BODY" --labels "LABELS" -``` - -**GitLab (via CLI)**: -```bash -glab issue create --title "TITLE" --description "BODY" --labels "LABELS" -``` - -**Fallback**: generate an importable CSV/JSON file - -### 7. Report - -Report: -- Number of issues created -- Issue URL list -- Any failures or warnings -- Task ID to issue number mapping - -### 8. Update Task File (Optional) - -If the user requests, update `tasks.md` to include issue references. diff --git a/.agents/tooling/generate_skill_mirrors.py b/.agents/tooling/generate_skill_mirrors.py new file mode 100644 index 000000000..edb279c24 --- /dev/null +++ b/.agents/tooling/generate_skill_mirrors.py @@ -0,0 +1,205 @@ +#!/usr/bin/env python3 +"""Generate .claude/skills/ mirrors from .agents/skills/ source files. + +Reads all .agents/skills/*/SKILL.md files and generates simplified mirrors +in .claude/skills//SKILL.md. Each mirror contains a generated header, +skill name, description, trigger rules, and a pointer back to the source of truth. + +Supports --check mode for CI validation that mirrors are up to date. + +Usage: + python3 .agents/tooling/generate_skill_mirrors.py # Generate mirrors + python3 .agents/tooling/generate_skill_mirrors.py --check # Verify mirrors are current +""" + +import argparse +import re +import sys +from pathlib import Path + +REPO_ROOT = Path(__file__).resolve().parent.parent.parent +SOURCE_DIR = REPO_ROOT / ".agents" / "skills" +MIRROR_DIR = REPO_ROOT / ".claude" / "skills" +GENERATED_HEADER_PREFIX = "", + "", + f"# {skill_name}", + "", + f"**Description**: {description}", + "", + ] + + if triggers: + lines.extend([ + "## When to Use", + "", + triggers, + "", + ]) + + lines.extend([ + "## Source of Truth", + "", + f"This file is auto-generated from `{source_path}`.", + "Do not edit this file directly. Edit the source and re-run:", + "", + "```bash", + "python3 .agents/tooling/generate_skill_mirrors.py", + "```", + ]) + + return "\n".join(lines) + "\n" + + +def discover_skills() -> list[tuple[str, Path]]: + """Find all skills with SKILL.md in .agents/skills/.""" + skills = [] + if not SOURCE_DIR.is_dir(): + return skills + for entry in sorted(SOURCE_DIR.iterdir()): + if entry.is_dir() and (entry / "SKILL.md").is_file(): + skills.append((entry.name, entry / "SKILL.md")) + return skills + + +def generate_mirrors() -> list[str]: + """Generate all mirrors. Returns list of generated skill names.""" + skills = discover_skills() + if not skills: + print("No skills found in .agents/skills/", file=sys.stderr) + return [] + + generated = [] + for skill_name, source_path in skills: + source_text = source_path.read_text(encoding="utf-8") + mirror_content = generate_mirror_content(skill_name, source_text) + mirror_path = MIRROR_DIR / skill_name / "SKILL.md" + mirror_path.parent.mkdir(parents=True, exist_ok=True) + mirror_path.write_text(mirror_content, encoding="utf-8") + generated.append(skill_name) + print(f" Generated: .claude/skills/{skill_name}/SKILL.md") + + return generated + + +def clean_orphans(current_skills: set[str]) -> list[str]: + """Remove mirror directories for skills that no longer exist in source.""" + if not MIRROR_DIR.is_dir(): + return [] + orphans = [] + for entry in sorted(MIRROR_DIR.iterdir()): + if entry.is_dir() and entry.name not in current_skills: + # Only clean directories that contain a generated SKILL.md + skill_file = entry / "SKILL.md" + if skill_file.is_file(): + text = skill_file.read_text(encoding="utf-8") + if text.startswith(GENERATED_HEADER_PREFIX): + skill_file.unlink() + entry.rmdir() + orphans.append(entry.name) + print(f" Removed orphan: .claude/skills/{entry.name}/") + return orphans + + +def check_mirrors() -> bool: + """Verify all mirrors are up to date. Returns True if all current.""" + skills = discover_skills() + all_current = True + + for skill_name, source_path in skills: + source_text = source_path.read_text(encoding="utf-8") + expected = generate_mirror_content(skill_name, source_text) + mirror_path = MIRROR_DIR / skill_name / "SKILL.md" + + if not mirror_path.is_file(): + print(f" MISSING: .claude/skills/{skill_name}/SKILL.md") + all_current = False + continue + + actual = mirror_path.read_text(encoding="utf-8") + if actual != expected: + print(f" STALE: .claude/skills/{skill_name}/SKILL.md") + all_current = False + else: + print(f" OK: .claude/skills/{skill_name}/SKILL.md") + + # Check for orphans + if MIRROR_DIR.is_dir(): + source_names = {name for name, _ in skills} + for entry in sorted(MIRROR_DIR.iterdir()): + if entry.is_dir() and entry.name not in source_names: + skill_file = entry / "SKILL.md" + if skill_file.is_file(): + text = skill_file.read_text(encoding="utf-8") + if text.startswith(GENERATED_HEADER_PREFIX): + print(f" ORPHAN: .claude/skills/{entry.name}/") + all_current = False + + return all_current + + +def main() -> int: + parser = argparse.ArgumentParser( + description="Generate .claude/skills/ mirrors from .agents/skills/ sources" + ) + parser.add_argument( + "--check", + action="store_true", + help="Verify mirrors are up to date (exit 0 if current, 1 if stale)", + ) + args = parser.parse_args() + + if args.check: + print("Checking skill mirrors...") + if check_mirrors(): + print("All mirrors are up to date.") + return 0 + print("Mirrors are out of date. Run without --check to regenerate.") + return 1 + + print("Generating skill mirrors...") + generated = generate_mirrors() + if generated: + source_names = set(generated) + clean_orphans(source_names) + print(f"Done. Generated {len(generated)} mirror(s).") + else: + print("No skills to generate.") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/.claude/skills/archive/SKILL.md b/.claude/skills/archive/SKILL.md new file mode 100644 index 000000000..e6b85a9d5 --- /dev/null +++ b/.claude/skills/archive/SKILL.md @@ -0,0 +1,19 @@ + + +# archive + +**Description**: Archive completed change proposals from docs/changes/ to docs/_archive/ after verifying preconditions. + +## When to Use + +- After a change is implemented, tested, reviewed, and merged +- As the final step of the `dev-workflow` skill + +## Source of Truth + +This file is auto-generated from `.agents/skills/archive/SKILL.md`. +Do not edit this file directly. Edit the source and re-run: + +```bash +python3 .agents/tooling/generate_skill_mirrors.py +``` diff --git a/.claude/skills/dev-workflow/SKILL.md b/.claude/skills/dev-workflow/SKILL.md new file mode 100644 index 000000000..c643b87c6 --- /dev/null +++ b/.claude/skills/dev-workflow/SKILL.md @@ -0,0 +1,14 @@ + + +# dev-workflow + +**Description**: Feature development workflow. Propose a change, plan implementation, execute with gates, and verify. + +## Source of Truth + +This file is auto-generated from `.agents/skills/dev-workflow/SKILL.md`. +Do not edit this file directly. Edit the source and re-run: + +```bash +python3 .agents/tooling/generate_skill_mirrors.py +``` diff --git a/.claude/skills/dmir-compiler-analysis/SKILL.md b/.claude/skills/dmir-compiler-analysis/SKILL.md new file mode 100644 index 000000000..0ef0f2ebb --- /dev/null +++ b/.claude/skills/dmir-compiler-analysis/SKILL.md @@ -0,0 +1,14 @@ + + +# dmir-compiler-analysis + +**Description**: Analyze DTVM's dMIR intermediate representation and compilation pipeline. Translates EVM bytecode sequences into dMIR pseudocode, then into x86 pseudocode, and evaluates performance cost at each stage. Use when the user asks about dMIR instructions, EVM-to-dMIR conversion, dMIR-to-x86 lowering, JIT compilation cost analysis, EVM opcode performance evaluation, or EVM->dMIR performance optimization. + +## Source of Truth + +This file is auto-generated from `.agents/skills/dmir-compiler-analysis/SKILL.md`. +Do not edit this file directly. Edit the source and re-run: + +```bash +python3 .agents/tooling/generate_skill_mirrors.py +``` diff --git a/.claude/skills/dtvm-perf-profile/SKILL.md b/.claude/skills/dtvm-perf-profile/SKILL.md new file mode 100644 index 000000000..64c7c6bdc --- /dev/null +++ b/.claude/skills/dtvm-perf-profile/SKILL.md @@ -0,0 +1,14 @@ + + +# dtvm-perf-profile + +**Description**: Profile DTVM execution using Linux perf and generate categorized analysis reports. Use when the user wants to profile a DTVM command, find performance hotspots, break down JIT-compiled EVM basic block execution time, analyze host function overhead, or mentions "perf", "profile", "hotspot", "breakdown", or "bottleneck" in the context of DTVM execution. The user provides a dtvm command line (including bytecode path, calldata, execution mode, etc.). + +## Source of Truth + +This file is auto-generated from `.agents/skills/dtvm-perf-profile/SKILL.md`. +Do not edit this file directly. Edit the source and re-run: + +```bash +python3 .agents/tooling/generate_skill_mirrors.py +``` diff --git a/.gitignore b/.gitignore index 50a5cb4d6..d4c1e0a7d 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,8 @@ bazel-testlogs # fuzzer /wtf + +# Claude Code local config (keep generated skill mirrors) +.claude/* +!.claude/skills/ +!.claude/skills/** diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 3e754e8cf..8ce69e08e 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -38,7 +38,7 @@ DTVM (DeTerministic Virtual Machine) is a next-generation deterministic virtual ### Architecture Patterns -- **Modular layered architecture**: modules under `src/` are organized by function (runtime, compiler, singlepass, evm, host, etc.), with each module's boundaries and contracts defined by spec.md files under `specs/modules/` +- **Modular layered architecture**: modules under `src/` are organized by function (runtime, compiler, singlepass, evm, host, etc.), with each module's boundaries and contracts defined by spec.md files under `docs/modules/` - **IR-driven**: all frontend instruction sets (Wasm, EVM, future RISC-V) are uniformly translated to dMIR, then the backend generates target code - **Multiple execution modes**: interpreter, singlepass JIT (single-pass compilation), multipass JIT (multi-pass optimized compilation, depends on LLVM 15) - **EVMC interface**: EVM compatibility provided through the standard EVMC interface @@ -125,9 +125,8 @@ Strictly follow [Conventional Commits](https://www.conventionalcommits.org/), se This project adopts specification-driven development (SDD): -1. **Module specs** (`specs/modules/`): each module has `spec.md` and `data-model.md`, defining module boundaries, API contracts, and data models -2. **Feature development** (`specs/features/`): new features follow the speckit workflow: specify → clarify → plan → tasks → implement -3. **Change management**: architecture-level changes are managed through the proposal process in `specs/features/` +1. **Module specs** (`docs/modules/`): each module has `spec.md` and `data-model.md`, defining module boundaries, API contracts, and data models +2. **Change proposals** (`docs/changes/`): new changes follow the `dev-workflow` skill: propose → plan → implement → verify → archive ### Change Decision Tree @@ -135,10 +134,10 @@ This project adopts specification-driven development (SDD): New requirement? ├─ Bug fix (restoring expected behavior)? → Fix directly ├─ Formatting/comments/typo fix? → Fix directly -├─ New feature/capability? → Create feature spec -├─ Breaking change? → Create feature spec -├─ Architecture change? → Create feature spec -└─ Unsure? → Create feature spec (safer) +├─ New feature/capability? → Create change proposal in docs/changes/ +├─ Breaking change? → Create change proposal in docs/changes/ +├─ Architecture change? → Create change proposal in docs/changes/ +└─ Unsure? → Create change proposal (safer) ``` ### Code Review Requirements @@ -185,8 +184,8 @@ New requirement? ### Communication Protocols - Technical discussions are conducted through GitHub Issues and Pull Requests -- Major design decisions are recorded in proposal documents under the specs directory -- AI-assisted development follows the behavioral guidelines in `AGENTS.md` and `specs/AGENTS.md` +- Major design decisions are recorded in proposal documents under the docs directory +- AI-assisted development follows the behavioral guidelines in `AGENTS.md` ### Decision Process @@ -196,10 +195,18 @@ New requirement? ### Knowledge Management -- Module contracts are documented in `specs/modules/` +- Module contracts are documented in `docs/modules/` +- Change proposals are in `docs/changes/` - Build and usage guides are in `docs/` - Constitution and memory documents are in `.specify/memory/` -- AI Agent behavioral rules are in `AGENTS.md` and `specs/AGENTS.md` +- AI Agent behavioral rules are in `AGENTS.md` + +### Agent Skills SSOT + +- `.agents/skills/` is the single source of truth for all agent skills +- `.claude/skills/` contains auto-generated mirrors for Claude Code consumption +- Mirrors must not be edited directly; regenerate with `python3 .agents/tooling/generate_skill_mirrors.py` +- Use `--check` mode in CI to verify mirrors stay in sync: `python3 .agents/tooling/generate_skill_mirrors.py --check` ### Editing Discipline @@ -238,13 +245,14 @@ DTVM/ ├── third_party/ # Third-party dependencies ├── tools/ # Helper tools ├── docs/ # Documentation -├── specs/ # SDD specs │ ├── modules/ # Module specs -│ └── features/ # Feature specs -├── .agents/skills/ # AI Agent skills +│ ├── changes/ # Change proposals +│ └── _archive/ # Archived changes +├── .agents/skills/ # AI Agent skills (SSOT) +├── .claude/skills/ # Auto-generated skill mirrors (do not edit) └── .specify/ # Spec-Kit configuration ``` --- -*Last updated: 2026-03-13* +*Last updated: 2026-04-08* diff --git a/.specify/scripts/bash/check-prerequisites.sh b/.specify/scripts/bash/check-prerequisites.sh deleted file mode 100755 index dbda3076b..000000000 --- a/.specify/scripts/bash/check-prerequisites.sh +++ /dev/null @@ -1,166 +0,0 @@ -#!/usr/bin/env bash - -# Consolidated prerequisite checking script -# -# This script provides unified prerequisite checking for Spec-Driven Development workflow. -# It replaces the functionality previously spread across multiple scripts. -# -# Usage: ./check-prerequisites.sh [OPTIONS] -# -# OPTIONS: -# --json Output in JSON format -# --require-tasks Require tasks.md to exist (for implementation phase) -# --include-tasks Include tasks.md in AVAILABLE_DOCS list -# --paths-only Only output path variables (no validation) -# --help, -h Show help message -# -# OUTPUTS: -# JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]} -# Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md -# Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc. - -set -e - -# Parse command line arguments -JSON_MODE=false -REQUIRE_TASKS=false -INCLUDE_TASKS=false -PATHS_ONLY=false - -for arg in "$@"; do - case "$arg" in - --json) - JSON_MODE=true - ;; - --require-tasks) - REQUIRE_TASKS=true - ;; - --include-tasks) - INCLUDE_TASKS=true - ;; - --paths-only) - PATHS_ONLY=true - ;; - --help|-h) - cat << 'EOF' -Usage: check-prerequisites.sh [OPTIONS] - -Consolidated prerequisite checking for Spec-Driven Development workflow. - -OPTIONS: - --json Output in JSON format - --require-tasks Require tasks.md to exist (for implementation phase) - --include-tasks Include tasks.md in AVAILABLE_DOCS list - --paths-only Only output path variables (no prerequisite validation) - --help, -h Show this help message - -EXAMPLES: - # Check task prerequisites (plan.md required) - ./check-prerequisites.sh --json - - # Check implementation prerequisites (plan.md + tasks.md required) - ./check-prerequisites.sh --json --require-tasks --include-tasks - - # Get feature paths only (no validation) - ./check-prerequisites.sh --paths-only - -EOF - exit 0 - ;; - *) - echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2 - exit 1 - ;; - esac -done - -# Source common functions -SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -source "$SCRIPT_DIR/common.sh" - -# Get feature paths and validate branch -eval $(get_feature_paths) -check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1 - -# If paths-only mode, output paths and exit (support JSON + paths-only combined) -if $PATHS_ONLY; then - if $JSON_MODE; then - # Minimal JSON paths payload (no validation performed) - printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \ - "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS" - else - echo "REPO_ROOT: $REPO_ROOT" - echo "BRANCH: $CURRENT_BRANCH" - echo "FEATURE_DIR: $FEATURE_DIR" - echo "FEATURE_SPEC: $FEATURE_SPEC" - echo "IMPL_PLAN: $IMPL_PLAN" - echo "TASKS: $TASKS" - fi - exit 0 -fi - -# Validate required directories and files -if [[ ! -d "$FEATURE_DIR" ]]; then - echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2 - echo "Run /speckit-specify first to create the feature structure." >&2 - exit 1 -fi - -if [[ ! -f "$IMPL_PLAN" ]]; then - echo "ERROR: plan.md not found in $FEATURE_DIR" >&2 - echo "Run /speckit-plan first to create the implementation plan." >&2 - exit 1 -fi - -# Check for tasks.md if required -if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then - echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2 - echo "Run /speckit-tasks first to create the task list." >&2 - exit 1 -fi - -# Build list of available documents -docs=() - -# Always check these optional docs -[[ -f "$RESEARCH" ]] && docs+=("research.md") -[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md") - -# Check contracts directory (only if it exists and has files) -if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then - docs+=("contracts/") -fi - -[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md") - -# Include tasks.md if requested and it exists -if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then - docs+=("tasks.md") -fi - -# Output results -if $JSON_MODE; then - # Build JSON array of documents - if [[ ${#docs[@]} -eq 0 ]]; then - json_docs="[]" - else - json_docs=$(printf '"%s",' "${docs[@]}") - json_docs="[${json_docs%,}]" - fi - - printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs" -else - # Text output - echo "FEATURE_DIR:$FEATURE_DIR" - echo "AVAILABLE_DOCS:" - - # Show status of each potential document - check_file "$RESEARCH" "research.md" - check_file "$DATA_MODEL" "data-model.md" - check_dir "$CONTRACTS_DIR" "contracts/" - check_file "$QUICKSTART" "quickstart.md" - - if $INCLUDE_TASKS; then - check_file "$TASKS" "tasks.md" - fi -fi diff --git a/.specify/scripts/bash/check-worktree.sh b/.specify/scripts/bash/check-worktree.sh deleted file mode 100755 index a5677f222..000000000 --- a/.specify/scripts/bash/check-worktree.sh +++ /dev/null @@ -1,31 +0,0 @@ -#!/usr/bin/env bash - -# Check if current directory is a git worktree or if worktrees exist for this repo -# Exit 0 (success) with "WORKTREE=true" if in worktree or worktrees exist -# Exit 1 (failure) with "WORKTREE=false" if not - -SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -source "$SCRIPT_DIR/common.sh" - -# Check if currently in a worktree -if is_worktree; then - echo "WORKTREE=true" - exit 0 -fi - -# Not in a worktree, check if worktrees exist for this repository -if git rev-parse --show-toplevel >/dev/null 2>&1; then - # Check if there are additional worktrees (git worktree list shows main repo + worktrees) - # Main repo line has format: /path/to/repo commit [branch] - # Worktree lines have the same format - # Count lines with [branch] suffix - these are worktrees (main repo also shows this) - # If more than 1 line, there are additional worktrees - worktree_count=$(git worktree list 2>/dev/null | wc -l) - if [ "$worktree_count" -gt 1 ]; then - echo "WORKTREE=true" - exit 0 - fi -fi - -echo "WORKTREE=false" -exit 1 diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh deleted file mode 100755 index 20fa07ad3..000000000 --- a/.specify/scripts/bash/common.sh +++ /dev/null @@ -1,209 +0,0 @@ -#!/usr/bin/env bash -# Common functions and variables for all scripts - -# Get repository root, with fallback for non-git repositories -get_repo_root() { - if git rev-parse --show-toplevel >/dev/null 2>&1; then - git rev-parse --show-toplevel - else - # Fall back to script location for non-git repos - local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - (cd "$script_dir/../../.." && pwd) - fi -} - -# Get current branch, with fallback for non-git repositories -get_current_branch() { - # First check if SPECIFY_FEATURE environment variable is set - if [[ -n "${SPECIFY_FEATURE:-}" ]]; then - echo "$SPECIFY_FEATURE" - return - fi - - # Then check git if available - if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then - git rev-parse --abbrev-ref HEAD - return - fi - - # For non-git repos, try to find the latest feature directory - local repo_root=$(get_repo_root) - local features_dir="$repo_root/specs/features" - - if [[ -d "$features_dir" ]]; then - local latest_feature="" - local highest=0 - - for dir in "$features_dir"/*; do - if [[ -d "$dir" ]]; then - local dirname=$(basename "$dir") - if [[ "$dirname" =~ ^([0-9]{3})- ]]; then - local number=${BASH_REMATCH[1]} - number=$((10#$number)) - if [[ "$number" -gt "$highest" ]]; then - highest=$number - latest_feature=$dirname - fi - fi - fi - done - - if [[ -n "$latest_feature" ]]; then - echo "$latest_feature" - return - fi - fi - - echo "main" # Final fallback -} - -# Check if we have git available -has_git() { - git rev-parse --show-toplevel >/dev/null 2>&1 -} - -check_feature_branch() { - local branch="$1" - local has_git_repo="$2" - - # For non-git repos, we can't enforce branch naming but still provide output - if [[ "$has_git_repo" != "true" ]]; then - echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2 - return 0 - fi - - # Support both "feature/###-xxx" and "###-xxx" formats - if [[ ! "$branch" =~ ^(feature/)?[0-9]{3}- ]]; then - echo "ERROR: Not on a feature branch. Current branch: $branch" >&2 - echo "Feature branches should be named like: feature/001-feature-name or 001-feature-name" >&2 - return 1 - fi - - return 0 -} - -get_feature_dir() { echo "$1/specs/features/$2"; } - -# Find feature directory by numeric prefix instead of exact branch match -# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature) -find_feature_dir_by_prefix() { - local repo_root="$1" - local branch_name="$2" - local features_dir="$repo_root/specs/features" - - # Remove feature/ prefix if present (support both "feature/###-xxx" and "###-xxx") - branch_name="${branch_name#feature/}" - - # Extract numeric prefix from branch (e.g., "004" from "004-whatever") - if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then - # If branch doesn't have numeric prefix, fall back to exact match - echo "$features_dir/$branch_name" - return - fi - - local prefix="${BASH_REMATCH[1]}" - - # Search for directories in specs/features/ that start with this prefix - local matches=() - if [[ -d "$features_dir" ]]; then - for dir in "$features_dir"/"$prefix"-*; do - if [[ -d "$dir" ]]; then - matches+=("$(basename "$dir")") - fi - done - fi - - # Handle results - if [[ ${#matches[@]} -eq 0 ]]; then - # No match found - return the branch name path (will fail later with clear error) - echo "$features_dir/$branch_name" - elif [[ ${#matches[@]} -eq 1 ]]; then - # Exactly one match - perfect! - echo "$features_dir/${matches[0]}" - else - # Multiple matches - this shouldn't happen with proper naming convention - echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2 - echo "Please ensure only one spec directory exists per numeric prefix." >&2 - echo "$features_dir/$branch_name" # Return something to avoid breaking the script - fi -} - -get_feature_paths() { - local repo_root=$(get_repo_root) - local current_branch=$(get_current_branch) - local has_git_repo="false" - - if has_git; then - has_git_repo="true" - fi - - # Use prefix-based lookup to support multiple branches per spec - local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch") - - printf 'REPO_ROOT=%q\n' "$repo_root" - printf 'CURRENT_BRANCH=%q\n' "$current_branch" - printf 'HAS_GIT=%q\n' "$has_git_repo" - printf 'FEATURE_DIR=%q\n' "$feature_dir" - printf 'FEATURE_SPEC=%q\n' "$feature_dir/spec.md" - printf 'IMPL_PLAN=%q\n' "$feature_dir/plan.md" - printf 'TASKS=%q\n' "$feature_dir/tasks.md" - printf 'RESEARCH=%q\n' "$feature_dir/research.md" - printf 'DATA_MODEL=%q\n' "$feature_dir/data-model.md" - printf 'QUICKSTART=%q\n' "$feature_dir/quickstart.md" - printf 'CONTRACTS_DIR=%q\n' "$feature_dir/contracts" -} - -check_file() { [[ -f "$1" ]] && echo " ✓ $2" || echo " ✗ $2"; } -check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo " ✓ $2" || echo " ✗ $2"; } - -# Detect if current directory is a git worktree -# Worktree has .git as a file (pointing to main repo's worktrees ref), normal repo has .git as a directory -is_worktree() { - if [ -f ".git" ]; then - # Check if .git file content points to worktrees - grep -q "worktrees" ".git" 2>/dev/null && return 0 - fi - return 1 -} - -# Get main repository root (parent directory for worktree) -get_main_repo_root() { - if is_worktree; then - # Worktree path is typically /path/to/main_repo/.git/worktrees/xxx - # Simpler approach: get worktree root via git rev-parse, then get its parent - local wt_root=$(git rev-parse --show-toplevel) - local wt_parent=$(dirname "$wt_root") - # If parent contains .git directory, it's the main repo - if [ -d "$wt_parent/.git" ]; then - echo "$wt_parent" - else - # Alternative: extract main repo path from .git file content - local git_file=".git" - if [ -f "$git_file" ]; then - # .git file content format: gitdir: /Users/user/repos/main_repo/.git/worktrees/feature-name - local gitdir=$(grep "^gitdir:" "$git_file" | sed 's/gitdir: //' | sed 's/\/.git\/worktrees\/.*//') - if [ -n "$gitdir" ]; then - echo "$gitdir" - else - echo "$wt_root" - fi - else - echo "$wt_root" - fi - fi - else - git rev-parse --show-toplevel - fi -} - -# Get worktree path (based on main repo name) -get_worktree_path() { - local main_repo="$1" - local feature_name="$2" - - # Get main repo name - local repo_name=$(basename "$main_repo") - - # Construct worktree path - echo "${main_repo}_${feature_name}" -} diff --git a/.specify/scripts/bash/create-new-feature.sh b/.specify/scripts/bash/create-new-feature.sh deleted file mode 100755 index 7db07bcf6..000000000 --- a/.specify/scripts/bash/create-new-feature.sh +++ /dev/null @@ -1,353 +0,0 @@ -#!/usr/bin/env bash - -set -e - -JSON_MODE=false -SHORT_NAME="" -BRANCH_NUMBER="" -WORKTREE_MODE=false -WORKTREE_PATH="" -ARGS=() -i=1 -while [ $i -le $# ]; do - arg="${!i}" - case "$arg" in - --json) - JSON_MODE=true - ;; - --short-name) - if [ $((i + 1)) -gt $# ]; then - echo 'Error: --short-name requires a value' >&2 - exit 1 - fi - i=$((i + 1)) - next_arg="${!i}" - # Check if the next argument is another option (starts with --) - if [[ "$next_arg" == --* ]]; then - echo 'Error: --short-name requires a value' >&2 - exit 1 - fi - SHORT_NAME="$next_arg" - ;; - --number) - if [ $((i + 1)) -gt $# ]; then - echo 'Error: --number requires a value' >&2 - exit 1 - fi - i=$((i + 1)) - next_arg="${!i}" - if [[ "$next_arg" == --* ]]; then - echo 'Error: --number requires a value' >&2 - exit 1 - fi - BRANCH_NUMBER="$next_arg" - ;; - --worktree) - WORKTREE_MODE=true - ;; - --help|-h) - echo "Usage: $0 [--json] [--short-name ] [--number N] [--worktree] " - echo "" - echo "Options:" - echo " --json Output in JSON format" - echo " --short-name Provide a custom short name (2-4 words) for the branch" - echo " --number N Specify branch number manually (overrides auto-detection)" - echo " --worktree Create a new git worktree instead of a regular branch" - echo " --help, -h Show this help message" - echo "" - echo "Examples:" - echo " $0 'Add user authentication system' --short-name 'user-auth'" - echo " $0 'Implement OAuth2 integration for API' --number 5" - echo " $0 'Add user authentication' --worktree" - exit 0 - ;; - *) - ARGS+=("$arg") - ;; - esac - i=$((i + 1)) -done - -FEATURE_DESCRIPTION="${ARGS[*]}" -if [ -z "$FEATURE_DESCRIPTION" ]; then - echo "Usage: $0 [--json] [--short-name ] [--number N] " >&2 - exit 1 -fi - -# Function to find the repository root by searching for existing project markers -find_repo_root() { - local dir="$1" - while [ "$dir" != "/" ]; do - if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then - echo "$dir" - return 0 - fi - dir="$(dirname "$dir")" - done - return 1 -} - -# Function to get highest number from specs directory -get_highest_from_specs() { - local specs_dir="$1" - local highest=0 - - if [ -d "$specs_dir" ]; then - for dir in "$specs_dir"/*; do - [ -d "$dir" ] || continue - dirname=$(basename "$dir") - number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0") - number=$((10#$number)) - if [ "$number" -gt "$highest" ]; then - highest=$number - fi - done - fi - - echo "$highest" -} - -# Function to get highest number from git branches -get_highest_from_branches() { - local highest=0 - - # Get all branches (local and remote) - branches=$(git branch -a 2>/dev/null || echo "") - - if [ -n "$branches" ]; then - while IFS= read -r branch; do - # Clean branch name: remove leading markers and remote prefixes - clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||') - - # Remove feature/ prefix if present - clean_branch=$(echo "$clean_branch" | sed 's|^feature/||') - - # Extract feature number if branch matches pattern ###-* - if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then - number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0") - number=$((10#$number)) - if [ "$number" -gt "$highest" ]; then - highest=$number - fi - fi - done <<< "$branches" - fi - - echo "$highest" -} - -# Function to check existing branches (local and remote) and return next available number -check_existing_branches() { - local specs_dir="$1" - - # Fetch all remotes to get latest branch info (suppress errors if no remotes) - git fetch --all --prune 2>/dev/null || true - - # Get highest number from ALL branches (not just matching short name) - local highest_branch=$(get_highest_from_branches) - - # Get highest number from ALL specs (not just matching short name) - local highest_spec=$(get_highest_from_specs "$specs_dir") - - # Take the maximum of both - local max_num=$highest_branch - if [ "$highest_spec" -gt "$max_num" ]; then - max_num=$highest_spec - fi - - # Return next number - echo $((max_num + 1)) -} - -# Function to clean and format a branch name -clean_branch_name() { - local name="$1" - echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//' -} - -# Resolve repository root. Prefer git information when available, but fall back -# to searching for repository markers so the workflow still functions in repositories that -# were initialised with --no-git. -SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -if git rev-parse --show-toplevel >/dev/null 2>&1; then - REPO_ROOT=$(git rev-parse --show-toplevel) - HAS_GIT=true -else - REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")" - if [ -z "$REPO_ROOT" ]; then - echo "Error: Could not determine repository root. Please run this script from within the repository." >&2 - exit 1 - fi - HAS_GIT=false -fi - -# Load common functions for worktree detection -source "$SCRIPT_DIR/common.sh" - -cd "$REPO_ROOT" - -SPECS_DIR="$REPO_ROOT/specs" -FEATURES_DIR="$SPECS_DIR/features" -mkdir -p "$FEATURES_DIR" - -# Function to generate branch name with stop word filtering and length filtering -generate_branch_name() { - local description="$1" - - # Common stop words to filter out - local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$" - - # Convert to lowercase and split into words - local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g') - - # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original) - local meaningful_words=() - for word in $clean_name; do - # Skip empty words - [ -z "$word" ] && continue - - # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms) - if ! echo "$word" | grep -qiE "$stop_words"; then - if [ ${#word} -ge 3 ]; then - meaningful_words+=("$word") - elif echo "$description" | grep -q "\b${word^^}\b"; then - # Keep short words if they appear as uppercase in original (likely acronyms) - meaningful_words+=("$word") - fi - fi - done - - # If we have meaningful words, use first 3-4 of them - if [ ${#meaningful_words[@]} -gt 0 ]; then - local max_words=3 - if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi - - local result="" - local count=0 - for word in "${meaningful_words[@]}"; do - if [ $count -ge $max_words ]; then break; fi - if [ -n "$result" ]; then result="$result-"; fi - result="$result$word" - count=$((count + 1)) - done - echo "$result" - else - # Fallback to original logic if no meaningful words found - local cleaned=$(clean_branch_name "$description") - echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//' - fi -} - -# Generate branch name -if [ -n "$SHORT_NAME" ]; then - # Use provided short name, just clean it up - BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME") -else - # Generate from description with smart filtering - BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION") -fi - -# Determine branch number -if [ -z "$BRANCH_NUMBER" ]; then - if [ "$HAS_GIT" = true ]; then - # Check existing branches on remotes - BRANCH_NUMBER=$(check_existing_branches "$FEATURES_DIR") - else - # Fall back to local directory check - HIGHEST=$(get_highest_from_specs "$FEATURES_DIR") - BRANCH_NUMBER=$((HIGHEST + 1)) - fi -fi - -# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal) -FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))") -FEATURE_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}" -GIT_BRANCH_NAME="feature/${FEATURE_NAME}" - -# GitHub enforces a 244-byte limit on branch names -# Validate and truncate if necessary -MAX_BRANCH_LENGTH=244 -if [ ${#GIT_BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then - # Calculate how much we need to trim from suffix - # Account for: "feature/" (8) + feature number (3) + hyphen (1) = 12 chars - MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 12)) - - # Truncate suffix at word boundary if possible - TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH) - # Remove trailing hyphen if truncation created one - TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//') - - ORIGINAL_BRANCH_NAME="$GIT_BRANCH_NAME" - FEATURE_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}" - GIT_BRANCH_NAME="feature/${FEATURE_NAME}" - - >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit" - >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)" - >&2 echo "[specify] Truncated to: $GIT_BRANCH_NAME (${#GIT_BRANCH_NAME} bytes)" -fi - -if [ "$HAS_GIT" = true ]; then - if [ "$WORKTREE_MODE" = true ]; then - # Create worktree - WORKTREE_PATH=$(get_worktree_path "$REPO_ROOT" "$FEATURE_NAME") - - # Ensure parent directory exists - mkdir -p "$(dirname "$WORKTREE_PATH")" - - # Create worktree on new branch (-b must come before path) - git worktree add -b "$GIT_BRANCH_NAME" "$WORKTREE_PATH" - - echo "[specify] Worktree created at: $WORKTREE_PATH" - echo "[specify] Please navigate to this directory to continue." - else - # Regular branch creation - git checkout -b "$GIT_BRANCH_NAME" - fi -else - >&2 echo "[specify] Warning: Git repository not detected; skipped branch/worktree creation for $GIT_BRANCH_NAME" -fi - -# Determine where to create the feature directory -if [ "$WORKTREE_MODE" = true ]; then - # In worktree mode, use worktree root for specs - WORKTREE_SPECS_DIR="$WORKTREE_PATH/specs/features" - FEATURE_DIR="$WORKTREE_SPECS_DIR/$FEATURE_NAME" - mkdir -p "$FEATURE_DIR" - - # Template path is always in the main repo (worktree has .specify too, but template should be shared) - TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md" - SPEC_FILE="$FEATURE_DIR/spec.md" - if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi -else - # Normal mode: use main repo for specs - FEATURE_DIR="$FEATURES_DIR/$FEATURE_NAME" - mkdir -p "$FEATURE_DIR" - - TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md" - SPEC_FILE="$FEATURE_DIR/spec.md" - if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi -fi - -# Set the SPECIFY_FEATURE environment variable for the current session -# Use FEATURE_NAME (without feature/ prefix) for directory lookup compatibility -export SPECIFY_FEATURE="$FEATURE_NAME" - -if $JSON_MODE; then - if [ "$WORKTREE_MODE" = true ]; then - printf '{"BRANCH_NAME":"%s","FEATURE_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s","WORKTREE_PATH":"%s","WORKTREE_MODE":"true"}\n' "$GIT_BRANCH_NAME" "$FEATURE_NAME" "$SPEC_FILE" "$FEATURE_NUM" "$WORKTREE_PATH" - else - printf '{"BRANCH_NAME":"%s","FEATURE_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$GIT_BRANCH_NAME" "$FEATURE_NAME" "$SPEC_FILE" "$FEATURE_NUM" - fi -else - echo "BRANCH_NAME: $GIT_BRANCH_NAME" - echo "FEATURE_NAME: $FEATURE_NAME" - echo "SPEC_FILE: $SPEC_FILE" - echo "FEATURE_NUM: $FEATURE_NUM" - if [ "$WORKTREE_MODE" = true ]; then - echo "WORKTREE_PATH: $WORKTREE_PATH" - echo "WORKTREE_MODE: true" - echo "Please navigate to $WORKTREE_PATH to continue." - fi - echo "SPECIFY_FEATURE environment variable set to: $FEATURE_NAME" -fi diff --git a/.specify/scripts/bash/setup-plan.sh b/.specify/scripts/bash/setup-plan.sh deleted file mode 100755 index 7e23de40f..000000000 --- a/.specify/scripts/bash/setup-plan.sh +++ /dev/null @@ -1,60 +0,0 @@ -#!/usr/bin/env bash - -set -e - -# Parse command line arguments -JSON_MODE=false -ARGS=() - -for arg in "$@"; do - case "$arg" in - --json) - JSON_MODE=true - ;; - --help|-h) - echo "Usage: $0 [--json]" - echo " --json Output results in JSON format" - echo " --help Show this help message" - exit 0 - ;; - *) - ARGS+=("$arg") - ;; - esac -done - -# Get script directory and load common functions -SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -source "$SCRIPT_DIR/common.sh" - -# Get all paths and variables from common functions -eval $(get_feature_paths) - -# Check if we're on a proper feature branch (only for git repos) -check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1 - -# Ensure the feature directory exists -mkdir -p "$FEATURE_DIR" - -# Copy plan template if it exists -TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md" -if [[ -f "$TEMPLATE" ]]; then - cp "$TEMPLATE" "$IMPL_PLAN" - echo "Copied plan template to $IMPL_PLAN" -else - echo "Warning: Plan template not found at $TEMPLATE" - # Create a basic plan file if template doesn't exist - touch "$IMPL_PLAN" -fi - -# Output results -if $JSON_MODE; then - printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \ - "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT" -else - echo "FEATURE_SPEC: $FEATURE_SPEC" - echo "IMPL_PLAN: $IMPL_PLAN" - echo "SPECS_DIR: $FEATURE_DIR" - echo "BRANCH: $CURRENT_BRANCH" - echo "HAS_GIT: $HAS_GIT" -fi diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh deleted file mode 100755 index 47283c370..000000000 --- a/.specify/scripts/bash/update-agent-context.sh +++ /dev/null @@ -1,797 +0,0 @@ -#!/usr/bin/env bash - -# Update agent context files with information from plan.md -# -# This script maintains AI agent context files by parsing feature specifications -# and updating agent-specific configuration files with project information. -# -# MAIN FUNCTIONS: -# 1. Environment Validation -# - Verifies git repository structure and branch information -# - Checks for required plan.md files and templates -# - Validates file permissions and accessibility -# -# 2. Plan Data Extraction -# - Parses plan.md files to extract project metadata -# - Identifies language/version, frameworks, databases, and project types -# - Handles missing or incomplete specification data gracefully -# -# 3. Agent File Management -# - Creates new agent context files from templates when needed -# - Updates existing agent files with new project information -# - Preserves manual additions and custom configurations -# - Supports multiple AI agent formats and directory structures -# -# 4. Content Generation -# - Generates language-specific build/test commands -# - Creates appropriate project directory structures -# - Updates technology stacks and recent changes sections -# - Maintains consistent formatting and timestamps -# -# 5. Multi-Agent Support -# - Handles agent-specific file paths and naming conventions -# - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, or Amazon Q Developer CLI -# - Can update single agents or all existing agent files -# - Creates default Claude file if no agent files exist -# -# Usage: ./update-agent-context.sh [agent_type] -# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder -# Leave empty to update all existing agent files - -set -e - -# Enable strict error handling -set -u -set -o pipefail - -#============================================================================== -# Configuration and Global Variables -#============================================================================== - -# Get script directory and load common functions -SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -source "$SCRIPT_DIR/common.sh" - -# Get all paths and variables from common functions -eval $(get_feature_paths) - -NEW_PLAN="$IMPL_PLAN" # Alias for compatibility with existing code -AGENT_TYPE="${1:-}" - -# Agent-specific file paths -CLAUDE_FILE="$REPO_ROOT/CLAUDE.md" -GEMINI_FILE="$REPO_ROOT/GEMINI.md" -COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md" -CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc" -QWEN_FILE="$REPO_ROOT/QWEN.md" -AGENTS_FILE="$REPO_ROOT/AGENTS.md" -WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md" -KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md" -AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md" -ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md" -CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md" -QODER_FILE="$REPO_ROOT/QODER.md" -AMP_FILE="$REPO_ROOT/AGENTS.md" -SHAI_FILE="$REPO_ROOT/SHAI.md" -Q_FILE="$REPO_ROOT/AGENTS.md" -BOB_FILE="$REPO_ROOT/AGENTS.md" - -# Template file -TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md" - -# Global variables for parsed plan data -NEW_LANG="" -NEW_FRAMEWORK="" -NEW_DB="" -NEW_PROJECT_TYPE="" - -#============================================================================== -# Utility Functions -#============================================================================== - -log_info() { - echo "INFO: $1" -} - -log_success() { - echo "✓ $1" -} - -log_error() { - echo "ERROR: $1" >&2 -} - -log_warning() { - echo "WARNING: $1" >&2 -} - -# Cleanup function for temporary files -cleanup() { - local exit_code=$? - rm -f /tmp/agent_update_*_$$ - rm -f /tmp/manual_additions_$$ - exit $exit_code -} - -# Set up cleanup trap -trap cleanup EXIT INT TERM - -#============================================================================== -# Validation Functions -#============================================================================== - -validate_environment() { - # Check if we have a current branch/feature (git or non-git) - if [[ -z "$CURRENT_BRANCH" ]]; then - log_error "Unable to determine current feature" - if [[ "$HAS_GIT" == "true" ]]; then - log_info "Make sure you're on a feature branch" - else - log_info "Set SPECIFY_FEATURE environment variable or create a feature first" - fi - exit 1 - fi - - # Check if plan.md exists - if [[ ! -f "$NEW_PLAN" ]]; then - log_error "No plan.md found at $NEW_PLAN" - log_info "Make sure you're working on a feature with a corresponding spec directory" - if [[ "$HAS_GIT" != "true" ]]; then - log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first" - fi - exit 1 - fi - - # Check if template exists (needed for new files) - if [[ ! -f "$TEMPLATE_FILE" ]]; then - log_warning "Template file not found at $TEMPLATE_FILE" - log_warning "Creating new agent files will fail" - fi -} - -#============================================================================== -# Plan Parsing Functions -#============================================================================== - -extract_plan_field() { - local field_pattern="$1" - local plan_file="$2" - - grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \ - head -1 | \ - sed "s|^\*\*${field_pattern}\*\*: ||" | \ - sed 's/^[ \t]*//;s/[ \t]*$//' | \ - grep -v "NEEDS CLARIFICATION" | \ - grep -v "^N/A$" || echo "" -} - -parse_plan_data() { - local plan_file="$1" - - if [[ ! -f "$plan_file" ]]; then - log_error "Plan file not found: $plan_file" - return 1 - fi - - if [[ ! -r "$plan_file" ]]; then - log_error "Plan file is not readable: $plan_file" - return 1 - fi - - log_info "Parsing plan data from $plan_file" - - NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file") - NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file") - NEW_DB=$(extract_plan_field "Storage" "$plan_file") - NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file") - - # Log what we found - if [[ -n "$NEW_LANG" ]]; then - log_info "Found language: $NEW_LANG" - else - log_warning "No language information found in plan" - fi - - if [[ -n "$NEW_FRAMEWORK" ]]; then - log_info "Found framework: $NEW_FRAMEWORK" - fi - - if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then - log_info "Found database: $NEW_DB" - fi - - if [[ -n "$NEW_PROJECT_TYPE" ]]; then - log_info "Found project type: $NEW_PROJECT_TYPE" - fi -} - -format_technology_stack() { - local lang="$1" - local framework="$2" - local parts=() - - # Add non-empty parts - [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang") - [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework") - - # Join with proper formatting - if [[ ${#parts[@]} -eq 0 ]]; then - echo "" - elif [[ ${#parts[@]} -eq 1 ]]; then - echo "${parts[0]}" - else - # Join multiple parts with " + " - local result="${parts[0]}" - for ((i=1; i<${#parts[@]}; i++)); do - result="$result + ${parts[i]}" - done - echo "$result" - fi -} - -#============================================================================== -# Template and Content Generation Functions -#============================================================================== - -get_project_structure() { - local project_type="$1" - - if [[ "$project_type" == *"web"* ]]; then - echo "backend/\\nfrontend/\\ntests/" - else - echo "src/\\ntests/" - fi -} - -get_commands_for_language() { - local lang="$1" - - case "$lang" in - *"Python"*) - echo "cd src && pytest && ruff check ." - ;; - *"Rust"*) - echo "cargo test && cargo clippy" - ;; - *"JavaScript"*|*"TypeScript"*) - echo "npm test \\&\\& npm run lint" - ;; - *) - echo "# Add commands for $lang" - ;; - esac -} - -get_language_conventions() { - local lang="$1" - echo "$lang: Follow standard conventions" -} - -create_new_agent_file() { - local target_file="$1" - local temp_file="$2" - local project_name="$3" - local current_date="$4" - - if [[ ! -f "$TEMPLATE_FILE" ]]; then - log_error "Template not found at $TEMPLATE_FILE" - return 1 - fi - - if [[ ! -r "$TEMPLATE_FILE" ]]; then - log_error "Template file is not readable: $TEMPLATE_FILE" - return 1 - fi - - log_info "Creating new agent context file from template..." - - if ! cp "$TEMPLATE_FILE" "$temp_file"; then - log_error "Failed to copy template file" - return 1 - fi - - # Replace template placeholders - local project_structure - project_structure=$(get_project_structure "$NEW_PROJECT_TYPE") - - local commands - commands=$(get_commands_for_language "$NEW_LANG") - - local language_conventions - language_conventions=$(get_language_conventions "$NEW_LANG") - - # Perform substitutions with error checking using safer approach - # Escape special characters for sed by using a different delimiter or escaping - local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g') - local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g') - local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g') - - # Build technology stack and recent change strings conditionally - local tech_stack - if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then - tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)" - elif [[ -n "$escaped_lang" ]]; then - tech_stack="- $escaped_lang ($escaped_branch)" - elif [[ -n "$escaped_framework" ]]; then - tech_stack="- $escaped_framework ($escaped_branch)" - else - tech_stack="- ($escaped_branch)" - fi - - local recent_change - if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then - recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework" - elif [[ -n "$escaped_lang" ]]; then - recent_change="- $escaped_branch: Added $escaped_lang" - elif [[ -n "$escaped_framework" ]]; then - recent_change="- $escaped_branch: Added $escaped_framework" - else - recent_change="- $escaped_branch: Added" - fi - - local substitutions=( - "s|\[PROJECT NAME\]|$project_name|" - "s|\[DATE\]|$current_date|" - "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|" - "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g" - "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|" - "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|" - "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|" - ) - - for substitution in "${substitutions[@]}"; do - if ! sed -i.bak -e "$substitution" "$temp_file"; then - log_error "Failed to perform substitution: $substitution" - rm -f "$temp_file" "$temp_file.bak" - return 1 - fi - done - - # Convert \n sequences to actual newlines - newline=$(printf '\n') - sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file" - - # Clean up backup files - rm -f "$temp_file.bak" "$temp_file.bak2" - - return 0 -} - - - -update_existing_agent_file() { - local target_file="$1" - local current_date="$2" - - log_info "Updating existing agent context file..." - - # Use a single temporary file for atomic update - local temp_file - temp_file=$(mktemp) || { - log_error "Failed to create temporary file" - return 1 - } - - # Process the file in one pass - local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK") - local new_tech_entries=() - local new_change_entry="" - - # Prepare new technology entries - if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then - new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)") - fi - - if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then - new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)") - fi - - # Prepare new change entry - if [[ -n "$tech_stack" ]]; then - new_change_entry="- $CURRENT_BRANCH: Added $tech_stack" - elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then - new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB" - fi - - # Check if sections exist in the file - local has_active_technologies=0 - local has_recent_changes=0 - - if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then - has_active_technologies=1 - fi - - if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then - has_recent_changes=1 - fi - - # Process file line by line - local in_tech_section=false - local in_changes_section=false - local tech_entries_added=false - local changes_entries_added=false - local existing_changes_count=0 - local file_ended=false - - while IFS= read -r line || [[ -n "$line" ]]; do - # Handle Active Technologies section - if [[ "$line" == "## Active Technologies" ]]; then - echo "$line" >> "$temp_file" - in_tech_section=true - continue - elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then - # Add new tech entries before closing the section - if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then - printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file" - tech_entries_added=true - fi - echo "$line" >> "$temp_file" - in_tech_section=false - continue - elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then - # Add new tech entries before empty line in tech section - if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then - printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file" - tech_entries_added=true - fi - echo "$line" >> "$temp_file" - continue - fi - - # Handle Recent Changes section - if [[ "$line" == "## Recent Changes" ]]; then - echo "$line" >> "$temp_file" - # Add new change entry right after the heading - if [[ -n "$new_change_entry" ]]; then - echo "$new_change_entry" >> "$temp_file" - fi - in_changes_section=true - changes_entries_added=true - continue - elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then - echo "$line" >> "$temp_file" - in_changes_section=false - continue - elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then - # Keep only first 2 existing changes - if [[ $existing_changes_count -lt 2 ]]; then - echo "$line" >> "$temp_file" - ((existing_changes_count++)) - fi - continue - fi - - # Update timestamp - if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then - echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file" - else - echo "$line" >> "$temp_file" - fi - done < "$target_file" - - # Post-loop check: if we're still in the Active Technologies section and haven't added new entries - if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then - printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file" - tech_entries_added=true - fi - - # If sections don't exist, add them at the end of the file - if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then - echo "" >> "$temp_file" - echo "## Active Technologies" >> "$temp_file" - printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file" - tech_entries_added=true - fi - - if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then - echo "" >> "$temp_file" - echo "## Recent Changes" >> "$temp_file" - echo "$new_change_entry" >> "$temp_file" - changes_entries_added=true - fi - - # Move temp file to target atomically - if ! mv "$temp_file" "$target_file"; then - log_error "Failed to update target file" - rm -f "$temp_file" - return 1 - fi - - return 0 -} -#============================================================================== -# Main Agent File Update Function -#============================================================================== - -update_agent_file() { - local target_file="$1" - local agent_name="$2" - - if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then - log_error "update_agent_file requires target_file and agent_name parameters" - return 1 - fi - - log_info "Updating $agent_name context file: $target_file" - - local project_name - project_name=$(basename "$REPO_ROOT") - local current_date - current_date=$(date +%Y-%m-%d) - - # Create directory if it doesn't exist - local target_dir - target_dir=$(dirname "$target_file") - if [[ ! -d "$target_dir" ]]; then - if ! mkdir -p "$target_dir"; then - log_error "Failed to create directory: $target_dir" - return 1 - fi - fi - - if [[ ! -f "$target_file" ]]; then - # Create new file from template - local temp_file - temp_file=$(mktemp) || { - log_error "Failed to create temporary file" - return 1 - } - - if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then - if mv "$temp_file" "$target_file"; then - log_success "Created new $agent_name context file" - else - log_error "Failed to move temporary file to $target_file" - rm -f "$temp_file" - return 1 - fi - else - log_error "Failed to create new agent file" - rm -f "$temp_file" - return 1 - fi - else - # Update existing file - if [[ ! -r "$target_file" ]]; then - log_error "Cannot read existing file: $target_file" - return 1 - fi - - if [[ ! -w "$target_file" ]]; then - log_error "Cannot write to existing file: $target_file" - return 1 - fi - - if update_existing_agent_file "$target_file" "$current_date"; then - log_success "Updated existing $agent_name context file" - else - log_error "Failed to update existing agent file" - return 1 - fi - fi - - return 0 -} - -#============================================================================== -# Agent Selection and Processing -#============================================================================== - -update_specific_agent() { - local agent_type="$1" - - case "$agent_type" in - claude) - update_agent_file "$CLAUDE_FILE" "Claude Code" - ;; - gemini) - update_agent_file "$GEMINI_FILE" "Gemini CLI" - ;; - copilot) - update_agent_file "$COPILOT_FILE" "GitHub Copilot" - ;; - cursor-agent) - update_agent_file "$CURSOR_FILE" "Cursor IDE" - ;; - qwen) - update_agent_file "$QWEN_FILE" "Qwen Code" - ;; - opencode) - update_agent_file "$AGENTS_FILE" "opencode" - ;; - codex) - update_agent_file "$AGENTS_FILE" "Codex CLI" - ;; - windsurf) - update_agent_file "$WINDSURF_FILE" "Windsurf" - ;; - kilocode) - update_agent_file "$KILOCODE_FILE" "Kilo Code" - ;; - auggie) - update_agent_file "$AUGGIE_FILE" "Auggie CLI" - ;; - roo) - update_agent_file "$ROO_FILE" "Roo Code" - ;; - codebuddy) - update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI" - ;; - qoder) - update_agent_file "$QODER_FILE" "Qoder CLI" - ;; - amp) - update_agent_file "$AMP_FILE" "Amp" - ;; - shai) - update_agent_file "$SHAI_FILE" "SHAI" - ;; - q) - update_agent_file "$Q_FILE" "Amazon Q Developer CLI" - ;; - bob) - update_agent_file "$BOB_FILE" "IBM Bob" - ;; - *) - log_error "Unknown agent type '$agent_type'" - log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder" - exit 1 - ;; - esac -} - -update_all_existing_agents() { - local found_agent=false - - # Check each possible agent file and update if it exists - if [[ -f "$CLAUDE_FILE" ]]; then - update_agent_file "$CLAUDE_FILE" "Claude Code" - found_agent=true - fi - - if [[ -f "$GEMINI_FILE" ]]; then - update_agent_file "$GEMINI_FILE" "Gemini CLI" - found_agent=true - fi - - if [[ -f "$COPILOT_FILE" ]]; then - update_agent_file "$COPILOT_FILE" "GitHub Copilot" - found_agent=true - fi - - if [[ -f "$CURSOR_FILE" ]]; then - update_agent_file "$CURSOR_FILE" "Cursor IDE" - found_agent=true - fi - - if [[ -f "$QWEN_FILE" ]]; then - update_agent_file "$QWEN_FILE" "Qwen Code" - found_agent=true - fi - - if [[ -f "$AGENTS_FILE" ]]; then - update_agent_file "$AGENTS_FILE" "Codex/opencode" - found_agent=true - fi - - if [[ -f "$WINDSURF_FILE" ]]; then - update_agent_file "$WINDSURF_FILE" "Windsurf" - found_agent=true - fi - - if [[ -f "$KILOCODE_FILE" ]]; then - update_agent_file "$KILOCODE_FILE" "Kilo Code" - found_agent=true - fi - - if [[ -f "$AUGGIE_FILE" ]]; then - update_agent_file "$AUGGIE_FILE" "Auggie CLI" - found_agent=true - fi - - if [[ -f "$ROO_FILE" ]]; then - update_agent_file "$ROO_FILE" "Roo Code" - found_agent=true - fi - - if [[ -f "$CODEBUDDY_FILE" ]]; then - update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI" - found_agent=true - fi - - if [[ -f "$SHAI_FILE" ]]; then - update_agent_file "$SHAI_FILE" "SHAI" - found_agent=true - fi - - if [[ -f "$QODER_FILE" ]]; then - update_agent_file "$QODER_FILE" "Qoder CLI" - found_agent=true - fi - - if [[ -f "$Q_FILE" ]]; then - update_agent_file "$Q_FILE" "Amazon Q Developer CLI" - found_agent=true - fi - - if [[ -f "$BOB_FILE" ]]; then - update_agent_file "$BOB_FILE" "IBM Bob" - found_agent=true - fi - - # If no agent files exist, create a default Claude file - if [[ "$found_agent" == false ]]; then - log_info "No existing agent files found, creating default Claude file..." - update_agent_file "$CLAUDE_FILE" "Claude Code" - fi -} -print_summary() { - echo - log_info "Summary of changes:" - - if [[ -n "$NEW_LANG" ]]; then - echo " - Added language: $NEW_LANG" - fi - - if [[ -n "$NEW_FRAMEWORK" ]]; then - echo " - Added framework: $NEW_FRAMEWORK" - fi - - if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then - echo " - Added database: $NEW_DB" - fi - - echo - - log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]" -} - -#============================================================================== -# Main Execution -#============================================================================== - -main() { - # Validate environment before proceeding - validate_environment - - log_info "=== Updating agent context files for feature $CURRENT_BRANCH ===" - - # Parse the plan file to extract project information - if ! parse_plan_data "$NEW_PLAN"; then - log_error "Failed to parse plan data" - exit 1 - fi - - # Process based on agent type argument - local success=true - - if [[ -z "$AGENT_TYPE" ]]; then - # No specific agent provided - update all existing agent files - log_info "No agent specified, updating all existing agent files..." - if ! update_all_existing_agents; then - success=false - fi - else - # Specific agent provided - update only that agent - log_info "Updating specific agent: $AGENT_TYPE" - if ! update_specific_agent "$AGENT_TYPE"; then - success=false - fi - fi - - # Print summary - print_summary - - if [[ "$success" == true ]]; then - log_success "Agent context update completed successfully" - exit 0 - else - log_error "Agent context update completed with errors" - exit 1 - fi -} - -# Execute main function if script is run directly -if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then - main "$@" -fi diff --git a/.specify/templates/agent-file-template.md b/.specify/templates/agent-file-template.md deleted file mode 100644 index c1d4750e9..000000000 --- a/.specify/templates/agent-file-template.md +++ /dev/null @@ -1,28 +0,0 @@ -# [Project Name] Development Guide - -Auto-generated from all feature plans. Last updated: [DATE] - -## Current Technology Stack - -[Extracted from all PLAN.MD files] - -## Project Structure - -```text -[Actual structure from plans] -``` - -## Common Commands - -[Commands for current technology stack only] - -## Coding Standards - -[Standards for currently used language only] - -## Recent Changes - -[Last 3 features and their additions] - - - diff --git a/.specify/templates/checklist-template.md b/.specify/templates/checklist-template.md deleted file mode 100644 index dfe5fa24d..000000000 --- a/.specify/templates/checklist-template.md +++ /dev/null @@ -1,40 +0,0 @@ -# [Check Type] Checklist: [Feature Name] - -**Purpose**: [Brief description of what this checklist covers] -**Created**: [DATE] -**Feature**: [Link to spec.md or related documentation] - -**Note**: This checklist is generated by the `speckit-checklist` skill based on feature context and requirements. - - - -## [Category 1] - -- [ ] CHK001 First checklist item with explicit action -- [ ] CHK002 Second checklist item -- [ ] CHK003 Third checklist item - -## [Category 2] - -- [ ] CHK004 Checklist item from another category -- [ ] CHK005 Checklist item with specific criteria -- [ ] CHK006 Last checklist item in this category - -## Notes - -- Check off when done: `[x]` -- Add comments or findings inline -- Link to related resources or documentation -- Items are numbered sequentially for easy reference diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md deleted file mode 100644 index 7faf63ce7..000000000 --- a/.specify/templates/plan-template.md +++ /dev/null @@ -1,102 +0,0 @@ -# Implementation Plan: [Feature Name] - -**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link] -**Input**: Feature specification from `/specs/features/[###-feature-name]/spec.md` - -**Description**: This template is filled by the `speckit-plan` skill. - -## Summary - -[Extracted from feature specification: main requirements + technical approach from research] - -## Technical Context - - - -**Language/Version**: [e.g. Python 3.11, Swift 5.9, Rust 1.75, or TBD] -**Key Dependencies**: [e.g. FastAPI, UIKit, LLVM, or TBD] -**Storage**: [If applicable, e.g. PostgreSQL, CoreData, file system, or N/A] -**Tests**: [e.g. pytest, XCTest, cargo test, or TBD] -**Target Platform**: [e.g. Linux server, iOS 15+, WASM, or TBD] -**Project Type**: [Monolith/Web/Mobile—determines source structure] -**Performance Goals**: [Domain-specific, e.g. 1000 req/s, 10k lines/sec, 60 fps, or TBD] -**Constraints**: [Domain-specific, e.g. <200ms p95, <100MB memory, offline-capable, or TBD] -**Scale/Scope**: [Domain-specific, e.g. 10k users, 1M LOC, 50 pages, or TBD] - -## Constitution Check - -*Gate: Must pass before Phase 0 research. Re-check after Phase 1 design.* - -[Gate items determined by constitution document] - -## Project Structure - -### Documentation (this feature) - -```text -specs/features/[###-feature]/ -├── plan.md # This file (speckit-plan skill output) -├── research.md # Phase 0 output (speckit-plan skill) -├── data-model.md # Phase 1 output (speckit-plan skill) -├── quickstart.md # Phase 1 output (speckit-plan skill) -├── contracts/ # Phase 1 output (speckit-plan skill) -└── tasks.md # Phase 2 output (speckit-tasks skill—not created by speckit-plan) -``` - -### Source Code (repository root) - - -```text -# [Delete if unused] Option 1: Monolith project (default) -src/ -├── models/ -├── services/ -├── cli/ -└── lib/ - -tests/ -├── contract/ -├── integration/ -└── unit/ - -# [Delete if unused] Option 2: Web app (when "frontend" + "backend" detected) -backend/ -├── src/ -│ ├── models/ -│ ├── services/ -│ └── api/ -└── tests/ - -frontend/ -├── src/ -│ ├── components/ -│ ├── pages/ -│ └── services/ -└── tests/ - -# [Delete if unused] Option 3: Mobile + API (when "iOS/Android" detected) -api/ -└── [same structure as backend above] - -ios/ or android/ -└── [Platform-specific structure: feature modules, UI flows, platform tests] -``` - -**Structure Decision**: [Record the selected structure and reference the actual directories above] - -## Complexity Tracking - -> **Fill only when constitution check has violations requiring justification** - -| Violation | Why Needed | Simpler Alternatives Rejected and Reason | -|-----------|------------|------------------------------------------| -| [e.g. 4th subproject] | [Current requirement] | [Why 3 subprojects are insufficient] | -| [e.g. Repository pattern] | [Specific problem] | [Why direct database access is insufficient] | diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md deleted file mode 100644 index 2fd185ecb..000000000 --- a/.specify/templates/spec-template.md +++ /dev/null @@ -1,135 +0,0 @@ -# Feature Specification: [Feature Name] - -**Feature Branch**: `[###-feature-name]` -**Created**: [DATE] -**Status**: Draft - ---- - -## Authoritative References - - - -- **Consumed Modules**: - - **[Module Name]**: [specs/modules/MODULE/](../../modules/MODULE/) - ---- - -**Input**: User description: "$ARGUMENTS" - -## User Scenarios & Testing *(Required)* - - - -### User Story 1 - [Brief Title] (Priority: P1) - -[Describe this user journey in natural language] - -**Priority Rationale**: [Explain the value and why this priority] - -**Independent Testing**: [Describe how to test independently—e.g. "Can be fully tested via [specific action], delivering [specific value]"] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] -2. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -### User Story 2 - [Brief Title] (Priority: P2) - -[Describe this user journey in natural language] - -**Priority Rationale**: [Explain the value and why this priority] - -**Independent Testing**: [Describe how to test independently] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -### User Story 3 - [Brief Title] (Priority: P3) - -[Describe this user journey in natural language] - -**Priority Rationale**: [Explain the value and why this priority] - -**Independent Testing**: [Describe how to test independently] - -**Acceptance Scenarios**: - -1. **Given** [initial state], **When** [action], **Then** [expected outcome] - ---- - -[Add more User Stories as needed, each with a priority assigned] - -### Edge Cases - - - -- What happens when [boundary condition]? -- How does the system handle [error scenario]? - -## Requirements *(Required)* - - - -### Functional Requirements - -- **FR-001**: The system must [specific capability, e.g. "allow users to create accounts"] -- **FR-002**: The system must [specific capability, e.g. "validate email addresses"] -- **FR-003**: Users must be able to [key interaction, e.g. "reset password"] -- **FR-004**: The system must [data requirement, e.g. "persist user preferences"] -- **FR-005**: The system must [behavior, e.g. "log all security events"] - -*Example of marking underspecified requirements:* - -- **FR-006**: The system must authenticate users via [TBD: authentication method not specified—email/password, SSO, OAuth?] -- **FR-007**: The system must retain user data [TBD: retention period not specified] - -### Key Entities *(Required if feature involves data)* - -- **[Entity 1]**: [What it represents, key attributes (no implementation details)] -- **[Entity 2]**: [What it represents, relationship with other entities] - -## Success Criteria *(Required)* - - - -### Measurable Outcomes - -- **SC-001**: [Measurable metric, e.g. "Users can complete account creation within 2 minutes"] -- **SC-002**: [Measurable metric, e.g. "No performance degradation under 1000 concurrent users"] -- **SC-003**: [User satisfaction metric, e.g. "90% of users complete the main task on first attempt"] -- **SC-004**: [Business metric, e.g. "Reduce [X]-related tickets by 50%"] diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md deleted file mode 100644 index f84d6210f..000000000 --- a/.specify/templates/tasks-template.md +++ /dev/null @@ -1,246 +0,0 @@ -# Task List: [Feature Name] - -**Input**: Design documents from `/specs/features/[###-feature-name]/` -**Prerequisites**: plan.md (required), spec.md (User Stories required), research.md, data-model.md, contracts/ - -**Tests**: The following examples include test tasks. Tests are optional—include only when explicitly required in the feature spec. - -**Organization**: Tasks are grouped by User Story to support independent implementation and testing of each Story. - -## Format: `[ID] [P?] [Story] Description` - -- **[P]**: Can run in parallel (different files, no dependencies) -- **[Story]**: User Story (e.g. US1, US2, US3) -- Description includes exact file path - -## Path Conventions - -- **Monolith project**: `src/`, `tests/` under repository root -- **Web app**: `backend/src/`, `frontend/src/` -- **Mobile**: `api/src/`, `ios/src/` or `android/src/` -- Paths below assume monolith—adjust per plan.md structure - - - -## Phase 1: Project Setup (Shared Infrastructure) - -**Purpose**: Project initialization and basic structure - -- [ ] T001 Create project structure per implementation plan -- [ ] T002 Initialize [language] project, configure [framework] dependencies -- [ ] T003 [P] Configure code checking and formatting tools - ---- - -## Phase 2: Infrastructure (Blocking Prerequisites) - -**Purpose**: Core infrastructure that must be completed before any User Story - -**⚠️ Critical**: Do NOT start any User Story until this phase is complete - -Base task examples (adjust per project): - -- [ ] T004 Set up database schema and migration framework -- [ ] T005 [P] Implement authentication/authorization framework -- [ ] T006 [P] Set up API routing and middleware structure -- [ ] T007 Create base models/entities required by all stories -- [ ] T008 Configure error handling and logging infrastructure -- [ ] T009 Set up environment configuration management - -**Checkpoint**: Infrastructure ready—User Story implementation can now begin - ---- - -## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP - -**Goal**: [Brief description of what this story delivers] - -**Independent Testing**: [How to verify this story runs independently] - -### User Story 1 Tests (optional—include only when explicitly required) ⚠️ - -> **Note: Write these tests first, ensure they fail before implementation** - -- [ ] T010 [P] [US1] Contract test for endpoint [endpoint] tests/contract/test_[name].py -- [ ] T011 [P] [US1] Integration test for user journey [journey] tests/integration/test_[name].py - -### User Story 1 Implementation - -- [ ] T012 [P] [US1] Create [Entity1] model src/models/[entity1].py -- [ ] T013 [P] [US1] Create [Entity2] model src/models/[entity2].py -- [ ] T014 [US1] Implement [Service] src/services/[service].py (depends on T012, T013) -- [ ] T015 [US1] Implement [endpoint/feature] src/[location]/[file].py -- [ ] T016 [US1] Add validation and error handling -- [ ] T017 [US1] Add logging for User Story 1 operations - -**Checkpoint**: User Story 1 should now be fully usable and independently testable - ---- - -## Phase 4: User Story 2 - [Title] (Priority: P2) - -**Goal**: [Brief description of what this story delivers] - -**Independent Testing**: [How to verify this story runs independently] - -### User Story 2 Tests (optional—include only when explicitly required) ⚠️ - -- [ ] T018 [P] [US2] Contract test for endpoint [endpoint] tests/contract/test_[name].py -- [ ] T019 [P] [US2] Integration test for user journey [journey] tests/integration/test_[name].py - -### User Story 2 Implementation - -- [ ] T020 [P] [US2] Create [Entity] model src/models/[entity].py -- [ ] T021 [US2] Implement [Service] src/services/[service].py -- [ ] T022 [US2] Implement [endpoint/feature] src/[location]/[file].py -- [ ] T023 [US2] Integrate with User Story 1 components (if needed) - -**Checkpoint**: Both User Story 1 and 2 should now work independently - ---- - -## Phase 5: User Story 3 - [Title] (Priority: P3) - -**Goal**: [Brief description of what this story delivers] - -**Independent Testing**: [How to verify this story runs independently] - -### User Story 3 Tests (optional—include only when explicitly required) ⚠️ - -- [ ] T024 [P] [US3] Contract test for endpoint [endpoint] tests/contract/test_[name].py -- [ ] T025 [P] [US3] Integration test for user journey [journey] tests/integration/test_[name].py - -### User Story 3 Implementation - -- [ ] T026 [P] [US3] Create [Entity] model src/models/[entity].py -- [ ] T027 [US3] Implement [Service] src/services/[service].py -- [ ] T028 [US3] Implement [endpoint/feature] src/[location]/[file].py - -**Checkpoint**: All User Stories should now run independently - ---- - -[Add more User Story phases as needed, following the same pattern] - ---- - -## Phase N: Polish and Cross-Cutting Concerns - -**Purpose**: Improvements that affect multiple User Stories - -- [ ] TXXX [P] Update documentation in docs/ -- [ ] TXXX Code cleanup and refactoring -- [ ] TXXX Cross-story performance optimization -- [ ] TXXX [P] Add unit tests (if required) tests/unit/ -- [ ] TXXX Security hardening -- [ ] TXXX Run quickstart.md verification - ---- - -## Dependencies and Execution Order - -### Phase Dependencies - -- **Setup (Phase 1)**: No dependencies—can start immediately -- **Infrastructure (Phase 2)**: Depends on setup completion—blocks all User Stories -- **User Stories (Phase 3+)**: All depend on infrastructure phase completion - - User Stories can be advanced in parallel (if resources allow) - - Or advance by priority order (P1 → P2 → P3) -- **Polish (final phase)**: Depends on completion of all target User Stories - -### Dependencies Between User Stories - -- **User Story 1 (P1)**: Can start after Infrastructure (Phase 2) completes—no dependency on other Stories -- **User Story 2 (P2)**: Can start after Infrastructure (Phase 2) completes—may integrate with US1 but should be independently testable -- **User Story 3 (P3)**: Can start after Infrastructure (Phase 2) completes—may integrate with US1/US2 but should be independently testable - -### Within Each User Story - -- Tests (if included) must be written first and confirmed failing before implementation -- Models before services -- Services before endpoints -- Core implementation before integration -- Move to next priority only after current Story is complete - -### Parallelization Opportunities - -- All [P]-labeled setup tasks can run in parallel -- All [P]-labeled infrastructure tasks can run in parallel within Phase 2 -- After infrastructure phase completes, all User Stories can start in parallel (if team has capacity) -- All [P]-labeled tests within a User Story can run in parallel -- [P]-labeled models within a Story can run in parallel -- Different User Stories can be developed in parallel by different team members - ---- - -## Parallel Example: User Story 1 - -```bash -# Start all User Story 1 tests (if required) simultaneously: -Task: "Contract test for endpoint [endpoint] tests/contract/test_[name].py" -Task: "Integration test for user journey [journey] tests/integration/test_[name].py" - -# Start all User Story 1 models simultaneously: -Task: "Create [Entity1] model src/models/[entity1].py" -Task: "Create [Entity2] model src/models/[entity2].py" -``` - ---- - -## Implementation Strategy - -### MVP First (User Story 1 only) - -1. Complete Phase 1: Setup -2. Complete Phase 2: Infrastructure (critical—blocks all Stories) -3. Complete Phase 3: User Story 1 -4. **Pause for verification**: Independently test User Story 1 -5. Ship when deployable/demonstrable - -### Incremental Delivery - -1. Complete setup + infrastructure → Base ready -2. Add User Story 1 → Independent test → Deploy/demo (MVP!) -3. Add User Story 2 → Independent test → Deploy/demo -4. Add User Story 3 → Independent test → Deploy/demo -5. Each Story adds value without breaking existing Stories - -### Parallel Team Strategy - -With multiple developers: - -1. Team completes setup + infrastructure together -2. After infrastructure completes: - - Developer A: User Story 1 - - Developer B: User Story 2 - - Developer C: User Story 3 -3. Each Story completed and integrated independently - ---- - -## Notes - -- [P] tasks = different files, no dependencies -- [Story] label maps tasks to specific User Story for traceability -- Each User Story should be completable and testable independently -- Verify tests fail first before starting implementation -- Commit after each task or logic group completes -- Pause at any Checkpoint to independently verify Story -- Avoid: vague tasks, same-file conflicts, cross-Story dependencies that break independence diff --git a/AGENTS.md b/AGENTS.md index d5b0043fb..7e5e3f012 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,6 @@ - -# OpenSpec Instructions - -These instructions are for AI assistants working in this project. - -Always open `@/openspec/AGENTS.md` when the request: -- Mentions planning or proposals (words like proposal, spec, change, plan) -- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work -- Sounds ambiguous and you need the authoritative spec before coding - -Use `@/openspec/AGENTS.md` to learn: -- How to create and apply change proposals -- Spec format and conventions -- Project structure and guidelines - -Keep this managed block so 'openspec update' can refresh the instructions. - - - # DTVM Agent Guide -Instructions for working in this repo beyond the OpenSpec block. +Instructions for AI assistants working in this repo. ## Project Snapshot @@ -35,7 +16,7 @@ Instructions for working in this repo beyond the OpenSpec block. - `evmc/`: EVM compatibility components - `rust_crate/`: Rust bindings - `tools/`: helper scripts and utilities -- `openspec/`: spec-driven change proposals and references +- `docs/`: documentation, module specifications, change proposals, and feature specs ## Build (CMake) @@ -66,6 +47,54 @@ Instructions for working in this repo beyond the OpenSpec block. - Update or add tests when behavior changes; call out if tests were not run. - When asked to commit, follow `docs/COMMIT_CONVENTION.md`. +## Workflow + +Use the `dev-workflow` skill for feature development. It covers the full cycle: propose, plan, implement, verify, and archive. + +For archiving completed features, use the standalone `archive` skill. + +## Change Decision Tree + +``` +New requirement? +├─ Bug fix (restore intended behavior)? -> Fix directly +├─ Formatting/comments/typos? -> Fix directly +├─ New feature/capability? -> Create change proposal in docs/changes/ +├─ Breaking change? -> Create change proposal in docs/changes/ +├─ Architecture change? -> Create change proposal in docs/changes/ +└─ Uncertain? -> Create change proposal (safer) +``` + +## Change Proposals + +New changes go in `docs/changes/YYYY-MM-DD-/README.md`. + +Choose a tier: +- **Full**: architecture changes, cross-module impact, new capabilities +- **Light**: single-module improvements, well-scoped enhancements + +See `docs/changes/README.md` for naming conventions and status definitions. + +## Module Consultation + +Before modifying code in a module, consult `docs/modules//spec.md` for boundaries, API contracts, and invariants. + +## General Guidelines + +- Do not duplicate module SSOT content in change proposals; use references +- When code conflicts with specifications, code takes precedence, but update specs to stay in sync +- Follow `docs/COMMIT_CONVENTION.md` for commit conventions +- Maintain determinism: avoid introducing host-specific non-deterministic behavior +- Prefer modifying code within `src/`; only modify `third_party/` when explicitly required + +## Agent Skills + +Skills are defined in `.agents/skills/` (single source of truth). `.claude/skills/` contains auto-generated mirrors for Claude Code; do not edit mirrors directly. After modifying any skill, regenerate mirrors: + +```bash +python3 .agents/tooling/generate_skill_mirrors.py +``` + ## Documentation Pointers - Overview: `README.md` diff --git a/specs/_archive/2026-01/add-evmc-vm-interface-lib/design.md b/docs/_archive/2026-01/add-evmc-vm-interface-lib/design.md similarity index 100% rename from specs/_archive/2026-01/add-evmc-vm-interface-lib/design.md rename to docs/_archive/2026-01/add-evmc-vm-interface-lib/design.md diff --git a/specs/_archive/2026-01/add-evmc-vm-interface-lib/proposal.md b/docs/_archive/2026-01/add-evmc-vm-interface-lib/proposal.md similarity index 100% rename from specs/_archive/2026-01/add-evmc-vm-interface-lib/proposal.md rename to docs/_archive/2026-01/add-evmc-vm-interface-lib/proposal.md diff --git a/specs/_archive/2026-01/add-evmc-vm-interface-lib/specs/evmc-vm-interface/spec.md b/docs/_archive/2026-01/add-evmc-vm-interface-lib/specs/evmc-vm-interface/spec.md similarity index 100% rename from specs/_archive/2026-01/add-evmc-vm-interface-lib/specs/evmc-vm-interface/spec.md rename to docs/_archive/2026-01/add-evmc-vm-interface-lib/specs/evmc-vm-interface/spec.md diff --git a/specs/_archive/2026-01/add-evmc-vm-interface-lib/tasks.md b/docs/_archive/2026-01/add-evmc-vm-interface-lib/tasks.md similarity index 100% rename from specs/_archive/2026-01/add-evmc-vm-interface-lib/tasks.md rename to docs/_archive/2026-01/add-evmc-vm-interface-lib/tasks.md diff --git a/specs/_archive/2026-02/add-clz-opcode/proposal.md b/docs/_archive/2026-02/add-clz-opcode/proposal.md similarity index 100% rename from specs/_archive/2026-02/add-clz-opcode/proposal.md rename to docs/_archive/2026-02/add-clz-opcode/proposal.md diff --git a/specs/_archive/2026-02/add-clz-opcode/specs/evm-execution/spec.md b/docs/_archive/2026-02/add-clz-opcode/specs/evm-execution/spec.md similarity index 100% rename from specs/_archive/2026-02/add-clz-opcode/specs/evm-execution/spec.md rename to docs/_archive/2026-02/add-clz-opcode/specs/evm-execution/spec.md diff --git a/specs/_archive/2026-02/add-clz-opcode/specs/evm-jit/spec.md b/docs/_archive/2026-02/add-clz-opcode/specs/evm-jit/spec.md similarity index 100% rename from specs/_archive/2026-02/add-clz-opcode/specs/evm-jit/spec.md rename to docs/_archive/2026-02/add-clz-opcode/specs/evm-jit/spec.md diff --git a/specs/_archive/2026-02/add-clz-opcode/tasks.md b/docs/_archive/2026-02/add-clz-opcode/tasks.md similarity index 100% rename from specs/_archive/2026-02/add-clz-opcode/tasks.md rename to docs/_archive/2026-02/add-clz-opcode/tasks.md diff --git a/specs/_archive/2026-02/add-jit-suitability-checker/design.md b/docs/_archive/2026-02/add-jit-suitability-checker/design.md similarity index 100% rename from specs/_archive/2026-02/add-jit-suitability-checker/design.md rename to docs/_archive/2026-02/add-jit-suitability-checker/design.md diff --git a/specs/_archive/2026-02/add-jit-suitability-checker/proposal.md b/docs/_archive/2026-02/add-jit-suitability-checker/proposal.md similarity index 100% rename from specs/_archive/2026-02/add-jit-suitability-checker/proposal.md rename to docs/_archive/2026-02/add-jit-suitability-checker/proposal.md diff --git a/specs/_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md b/docs/_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md similarity index 100% rename from specs/_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md rename to docs/_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md diff --git a/specs/_archive/2026-02/add-jit-suitability-checker/tasks.md b/docs/_archive/2026-02/add-jit-suitability-checker/tasks.md similarity index 100% rename from specs/_archive/2026-02/add-jit-suitability-checker/tasks.md rename to docs/_archive/2026-02/add-jit-suitability-checker/tasks.md diff --git a/specs/_archive/2026-03/add-evm-jit-fallback/design.md b/docs/_archive/2026-03/add-evm-jit-fallback/design.md similarity index 100% rename from specs/_archive/2026-03/add-evm-jit-fallback/design.md rename to docs/_archive/2026-03/add-evm-jit-fallback/design.md diff --git a/specs/_archive/2026-03/add-evm-jit-fallback/proposal.md b/docs/_archive/2026-03/add-evm-jit-fallback/proposal.md similarity index 100% rename from specs/_archive/2026-03/add-evm-jit-fallback/proposal.md rename to docs/_archive/2026-03/add-evm-jit-fallback/proposal.md diff --git a/specs/_archive/2026-03/add-evm-jit-fallback/specs/evm-execution/spec.md b/docs/_archive/2026-03/add-evm-jit-fallback/specs/evm-execution/spec.md similarity index 100% rename from specs/_archive/2026-03/add-evm-jit-fallback/specs/evm-execution/spec.md rename to docs/_archive/2026-03/add-evm-jit-fallback/specs/evm-execution/spec.md diff --git a/specs/_archive/2026-03/add-evm-jit-fallback/specs/evm-jit-fallback/spec.md b/docs/_archive/2026-03/add-evm-jit-fallback/specs/evm-jit-fallback/spec.md similarity index 100% rename from specs/_archive/2026-03/add-evm-jit-fallback/specs/evm-jit-fallback/spec.md rename to docs/_archive/2026-03/add-evm-jit-fallback/specs/evm-jit-fallback/spec.md diff --git a/specs/_archive/2026-03/add-evm-jit-fallback/tasks.md b/docs/_archive/2026-03/add-evm-jit-fallback/tasks.md similarity index 100% rename from specs/_archive/2026-03/add-evm-jit-fallback/tasks.md rename to docs/_archive/2026-03/add-evm-jit-fallback/tasks.md diff --git a/openspec/changes/update-evm-memory-block-precheck/design.md b/docs/_archive/2026-04/update-evm-memory-block-precheck/design.md similarity index 100% rename from openspec/changes/update-evm-memory-block-precheck/design.md rename to docs/_archive/2026-04/update-evm-memory-block-precheck/design.md diff --git a/openspec/changes/update-evm-memory-block-precheck/proposal.md b/docs/_archive/2026-04/update-evm-memory-block-precheck/proposal.md similarity index 96% rename from openspec/changes/update-evm-memory-block-precheck/proposal.md rename to docs/_archive/2026-04/update-evm-memory-block-precheck/proposal.md index bac776d5b..7589dce48 100644 --- a/openspec/changes/update-evm-memory-block-precheck/proposal.md +++ b/docs/_archive/2026-04/update-evm-memory-block-precheck/proposal.md @@ -121,12 +121,12 @@ The documented implementation also includes these analysis constraints: ### Specs -- `openspec/changes/update-evm-memory-block-precheck/specs/evm-jit/spec.md` +- `docs/_archive/2026-04/update-evm-memory-block-precheck/specs/evm-jit/spec.md` ### Design and Tasks -- `openspec/changes/update-evm-memory-block-precheck/design.md` -- `openspec/changes/update-evm-memory-block-precheck/tasks.md` +- `docs/_archive/2026-04/update-evm-memory-block-precheck/design.md` +- `docs/_archive/2026-04/update-evm-memory-block-precheck/tasks.md` ### Code already implementing this change diff --git a/openspec/changes/update-evm-memory-block-precheck/specs/evm-jit/spec.md b/docs/_archive/2026-04/update-evm-memory-block-precheck/specs/evm-jit/spec.md similarity index 100% rename from openspec/changes/update-evm-memory-block-precheck/specs/evm-jit/spec.md rename to docs/_archive/2026-04/update-evm-memory-block-precheck/specs/evm-jit/spec.md diff --git a/openspec/changes/update-evm-memory-block-precheck/tasks.md b/docs/_archive/2026-04/update-evm-memory-block-precheck/tasks.md similarity index 100% rename from openspec/changes/update-evm-memory-block-precheck/tasks.md rename to docs/_archive/2026-04/update-evm-memory-block-precheck/tasks.md diff --git a/specs/_archive/README.md b/docs/_archive/README.md similarity index 82% rename from specs/_archive/README.md rename to docs/_archive/README.md index bfa7e32ce..955f3a5ba 100644 --- a/specs/_archive/README.md +++ b/docs/_archive/README.md @@ -24,9 +24,9 @@ All entries follow the `YYYY-MM/short-name/` convention, grouped by the month th | 2026-02 | add-clz-opcode | CLZ opcode for EVM execution and JIT | | 2026-02 | add-jit-suitability-checker| JIT suitability checker for EVM | | 2026-03 | add-evm-jit-fallback | EVM JIT fallback mechanism | +| 2026-04 | update-evm-memory-block-precheck | EVM block-local memory precheck optimization | ## Notes - Archived specifications are for historical reference only and should not be modified. -- If rework is needed, create a new feature proposal under `specs/features/` referencing the original. -- Some entries use legacy openspec format (`proposal.md` + `design.md` + `specs/`) rather than the standard speckit template. +- If rework is needed, create a new change proposal under `docs/changes/` referencing the original. diff --git a/specs/architecture/README.md b/docs/architecture/README.md similarity index 100% rename from specs/architecture/README.md rename to docs/architecture/README.md diff --git a/docs/changes/README.md b/docs/changes/README.md new file mode 100644 index 000000000..e8430aef3 --- /dev/null +++ b/docs/changes/README.md @@ -0,0 +1,58 @@ +# Change Proposals + +This directory tracks proposed, accepted, and rejected changes to the DTVM project. + +## Naming Convention + +Each change lives in its own directory: + +``` +docs/changes/YYYY-MM-DD-/README.md +``` + +- `YYYY-MM-DD`: date the proposal was created +- `: short kebab-case description (e.g., add-risc-v-frontend)` + +## Status Definitions + +| Status | Meaning | +|--------|---------| +| **Proposed** | Under review, not yet approved for implementation | +| **Accepted** | Approved, ready for implementation | +| **Implemented** | Implementation complete and merged | +| **Rejected** | Declined with documented rationale | + +## Tiers + +### Full Tier + +Use for changes that affect architecture, cross-module contracts, or introduce new capabilities. Uses the [full template](template.md). + +Typical triggers: +- New module or major subsystem +- Breaking API changes +- Cross-cutting performance optimizations +- Changes to determinism or security guarantees + +### Light Tier + +Use for smaller, well-scoped changes with limited blast radius. Uses the [light template](template-light.md). + +Typical triggers: +- Single-module improvements +- Bug fixes with design implications +- Non-breaking enhancements + +## Current Proposals + +| Date | Name | Status | Tier | Description | +|------|------|--------|------|-------------| +| *(none yet)* | | | | | + +## Workflow + +1. Copy the appropriate template into a new `YYYY-MM-DD-/` directory +2. Fill in the change document +3. Update the table above with the new entry +4. Follow the `dev-workflow` skill for implementation +5. After merging, move the completed change to `docs/_archive/` diff --git a/docs/changes/template-light.md b/docs/changes/template-light.md new file mode 100644 index 000000000..d9c9781a3 --- /dev/null +++ b/docs/changes/template-light.md @@ -0,0 +1,24 @@ +# Change: + +- **Status**: Proposed +- **Date**: YYYY-MM-DD +- **Tier**: Light + +## Overview + +Brief summary of the change. + +## Motivation + +Why this change is needed. + +## Impact + +Which modules and contracts are affected. + +## Checklist + +- [ ] Implementation complete +- [ ] Tests added/updated +- [ ] Module specs in `docs/modules/` updated (if affected) +- [ ] Build and tests pass diff --git a/docs/changes/template.md b/docs/changes/template.md new file mode 100644 index 000000000..82b67b2a3 --- /dev/null +++ b/docs/changes/template.md @@ -0,0 +1,50 @@ +# Change: <title> + +- **Status**: Proposed +- **Date**: YYYY-MM-DD +- **Tier**: Full + +## Overview + +Brief summary of the change and what it accomplishes. + +## Motivation + +Why this change is needed. Reference relevant benchmarks, issues, or prior analysis. + +## Impact + +### Affected Modules + +List modules in `docs/modules/` that this change touches. + +### Affected Contracts + +List API or interface changes, if any. + +### Compatibility + +Describe breaking changes or migration requirements, if any. + +## Implementation Plan + +### Phase 1: <name> + +- [ ] Step description + +### Phase 2: <name> + +- [ ] Step description + +### Phase 3: <name> + +- [ ] Step description + +## Compatibility Notes + +Document any backwards-incompatible changes and migration path. + +## Risks + +- Risk 1: description and mitigation +- Risk 2: description and mitigation diff --git a/specs/code-style/README.md b/docs/code-style/README.md similarity index 100% rename from specs/code-style/README.md rename to docs/code-style/README.md diff --git a/specs/data-model/README.md b/docs/data-model/README.md similarity index 100% rename from specs/data-model/README.md rename to docs/data-model/README.md diff --git a/specs/modules/README.md b/docs/modules/README.md similarity index 100% rename from specs/modules/README.md rename to docs/modules/README.md diff --git a/specs/modules/action/data-model.md b/docs/modules/action/data-model.md similarity index 100% rename from specs/modules/action/data-model.md rename to docs/modules/action/data-model.md diff --git a/specs/modules/action/spec.md b/docs/modules/action/spec.md similarity index 100% rename from specs/modules/action/spec.md rename to docs/modules/action/spec.md diff --git a/specs/modules/cli/data-model.md b/docs/modules/cli/data-model.md similarity index 100% rename from specs/modules/cli/data-model.md rename to docs/modules/cli/data-model.md diff --git a/specs/modules/cli/spec.md b/docs/modules/cli/spec.md similarity index 100% rename from specs/modules/cli/spec.md rename to docs/modules/cli/spec.md diff --git a/specs/modules/common/data-model.md b/docs/modules/common/data-model.md similarity index 100% rename from specs/modules/common/data-model.md rename to docs/modules/common/data-model.md diff --git a/specs/modules/common/spec.md b/docs/modules/common/spec.md similarity index 100% rename from specs/modules/common/spec.md rename to docs/modules/common/spec.md diff --git a/specs/modules/compiler/data-model.md b/docs/modules/compiler/data-model.md similarity index 100% rename from specs/modules/compiler/data-model.md rename to docs/modules/compiler/data-model.md diff --git a/specs/modules/compiler/spec.md b/docs/modules/compiler/spec.md similarity index 97% rename from specs/modules/compiler/spec.md rename to docs/modules/compiler/spec.md index dda01bbe6..3e2d159f1 100644 --- a/specs/modules/compiler/spec.md +++ b/docs/modules/compiler/spec.md @@ -164,4 +164,4 @@ From `common/errors.h`, used by the compiler module: | action | performJITCompile, performEVMJITCompile invocations | | vm-interface | EVMAnalyzer, JIT fallback decisions | -- [EVM JIT spec (archived)](../../specs/_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md): EVM JIT requirements (Multipass-only, suitability analysis, RA-expensive classification) +- [EVM JIT spec (archived)](../../_archive/2026-02/add-jit-suitability-checker/specs/evm-jit/spec.md): EVM JIT requirements (Multipass-only, suitability analysis, RA-expensive classification) diff --git a/specs/modules/evm/data-model.md b/docs/modules/evm/data-model.md similarity index 100% rename from specs/modules/evm/data-model.md rename to docs/modules/evm/data-model.md diff --git a/specs/modules/evm/spec.md b/docs/modules/evm/spec.md similarity index 100% rename from specs/modules/evm/spec.md rename to docs/modules/evm/spec.md diff --git a/specs/modules/host/data-model.md b/docs/modules/host/data-model.md similarity index 100% rename from specs/modules/host/data-model.md rename to docs/modules/host/data-model.md diff --git a/specs/modules/host/spec.md b/docs/modules/host/spec.md similarity index 100% rename from specs/modules/host/spec.md rename to docs/modules/host/spec.md diff --git a/specs/modules/platform/data-model.md b/docs/modules/platform/data-model.md similarity index 100% rename from specs/modules/platform/data-model.md rename to docs/modules/platform/data-model.md diff --git a/specs/modules/platform/spec.md b/docs/modules/platform/spec.md similarity index 100% rename from specs/modules/platform/spec.md rename to docs/modules/platform/spec.md diff --git a/specs/modules/runtime/data-model.md b/docs/modules/runtime/data-model.md similarity index 100% rename from specs/modules/runtime/data-model.md rename to docs/modules/runtime/data-model.md diff --git a/specs/modules/runtime/spec.md b/docs/modules/runtime/spec.md similarity index 100% rename from specs/modules/runtime/spec.md rename to docs/modules/runtime/spec.md diff --git a/specs/modules/rust-bindings/data-model.md b/docs/modules/rust-bindings/data-model.md similarity index 100% rename from specs/modules/rust-bindings/data-model.md rename to docs/modules/rust-bindings/data-model.md diff --git a/specs/modules/rust-bindings/spec.md b/docs/modules/rust-bindings/spec.md similarity index 100% rename from specs/modules/rust-bindings/spec.md rename to docs/modules/rust-bindings/spec.md diff --git a/specs/modules/singlepass/data-model.md b/docs/modules/singlepass/data-model.md similarity index 100% rename from specs/modules/singlepass/data-model.md rename to docs/modules/singlepass/data-model.md diff --git a/specs/modules/singlepass/spec.md b/docs/modules/singlepass/spec.md similarity index 99% rename from specs/modules/singlepass/spec.md rename to docs/modules/singlepass/spec.md index ca58d25a4..eed0cbca1 100644 --- a/specs/modules/singlepass/spec.md +++ b/docs/modules/singlepass/spec.md @@ -147,5 +147,5 @@ Update these assertions when changing `Instance` layout. |-------------|-------------| | action | performJITCompile, WASMByteCodeVisitor driver | -- Data model: `specs/modules/singlepass/data-model.md` +- Data model: `data-model.md` - Build: `docs/start.md` (`ZEN_ENABLE_SINGLEPASS_JIT`) diff --git a/specs/modules/tests/data-model.md b/docs/modules/tests/data-model.md similarity index 100% rename from specs/modules/tests/data-model.md rename to docs/modules/tests/data-model.md diff --git a/specs/modules/tests/spec.md b/docs/modules/tests/spec.md similarity index 95% rename from specs/modules/tests/spec.md rename to docs/modules/tests/spec.md index d2be45c7b..803150d82 100644 --- a/specs/modules/tests/spec.md +++ b/docs/modules/tests/spec.md @@ -110,7 +110,7 @@ This module does not include: EVM interpreter (evm), Host implementation (host), ## Cross-References -- [specs/testing/README.md](../../testing/README.md) — Full testing guide -- [specs/modules/evm/spec.md](../evm/spec.md) — EVM interpreter spec -- [specs/modules/runtime/spec.md](../runtime/spec.md) — Runtime and instances -- [AGENTS.md](../../AGENTS.md) — Build and test commands +- [testing/README.md](../../testing/README.md) — Full testing guide +- [modules/evm/spec.md](../evm/spec.md) — EVM interpreter spec +- [modules/runtime/spec.md](../runtime/spec.md) — Runtime and instances +- [AGENTS.md](../../../AGENTS.md) — Build and test commands diff --git a/specs/modules/tools/spec.md b/docs/modules/tools/spec.md similarity index 94% rename from specs/modules/tools/spec.md rename to docs/modules/tools/spec.md index 7a1cedb9a..9340347a3 100644 --- a/specs/modules/tools/spec.md +++ b/docs/modules/tools/spec.md @@ -90,6 +90,6 @@ This module does not include: Build system (CMake), test framework (gtest/ctest) ## Cross-References -- [specs/testing/README.md](../../testing/README.md) — Test run instructions -- [docs/start.md](../../../docs/start.md) — Build and dependencies -- [specs/modules/tests/spec.md](../tests/spec.md) — Test module +- [testing/README.md](../../testing/README.md) — Test run instructions +- [docs/start.md](../../start.md) — Build and dependencies +- [modules/tests/spec.md](../tests/spec.md) — Test module diff --git a/specs/modules/utils/data-model.md b/docs/modules/utils/data-model.md similarity index 100% rename from specs/modules/utils/data-model.md rename to docs/modules/utils/data-model.md diff --git a/specs/modules/utils/spec.md b/docs/modules/utils/spec.md similarity index 100% rename from specs/modules/utils/spec.md rename to docs/modules/utils/spec.md diff --git a/specs/modules/vm-interface/data-model.md b/docs/modules/vm-interface/data-model.md similarity index 100% rename from specs/modules/vm-interface/data-model.md rename to docs/modules/vm-interface/data-model.md diff --git a/specs/modules/vm-interface/spec.md b/docs/modules/vm-interface/spec.md similarity index 100% rename from specs/modules/vm-interface/spec.md rename to docs/modules/vm-interface/spec.md diff --git a/specs/testing/README.md b/docs/testing/README.md similarity index 100% rename from specs/testing/README.md rename to docs/testing/README.md diff --git a/specs/AGENTS.md b/specs/AGENTS.md deleted file mode 100644 index a266fcdde..000000000 --- a/specs/AGENTS.md +++ /dev/null @@ -1,51 +0,0 @@ -# AI Agent Behavior Rules - -SDD workflow guidelines for AI coding assistants. - -## SDD Workflow - -This project uses the Spec-Kit + SSOT spec-driven development model: - -1. **Module Specifications** (`specs/modules/`): Each module has `spec.md` and `data-model.md` defining module boundaries, API contracts, and data models -2. **Feature Development** (`specs/features/`): New features follow the speckit workflow: specify -> clarify -> plan -> tasks -> implement -3. **Change Management**: Architecture-level changes are managed through the proposal process in `specs/features/` - -## Available Skills - -The following speckit sub-skills are located in `.agents/skills/`: - -| Skill | Purpose | -|-------|---------| -| `speckit-specify` | Create feature specifications from natural language | -| `speckit-clarify` | Clarify ambiguities in specifications | -| `speckit-plan` | Generate technical design artifacts | -| `speckit-tasks` | Generate actionable task lists | -| `speckit-implement` | Execute implementation by tasks | -| `speckit-dev-workflow` | Complete development workflow orchestration | -| `speckit-constitution` | Define project principles | -| `speckit-checklist` | Generate checklists | -| `speckit-analyze` | Analyze consistency | -| `speckit-taskstoissues` | Convert tasks to issues | -| `speckit-archive` | Archive completed features | - -## Change Decision Tree - -``` -New requirement? -├─ Bug fix (restore intended behavior)? → Fix directly -├─ Formatting/comments/typos? → Fix directly -├─ New feature/capability? → Create feature specification -├─ Breaking change? → Create feature specification -├─ Architecture change? → Create feature specification -└─ Uncertain? → Create feature specification (safer) -``` - -## Guidelines - -- Before modifying module code, consult `specs/modules/<module>/spec.md` for module contracts -- For new feature development, prefer `speckit-dev-workflow` or step-by-step sub-skills -- Do not duplicate module SSOT content in feature specifications; use references -- When code conflicts with specifications, code takes precedence, but specifications should be updated to stay in sync -- Follow `docs/COMMIT_CONVENTION.md` for commit conventions -- Maintain determinism: avoid introducing host-specific non-deterministic behavior -- Prefer modifying code within `src/`; only modify `third_party/` when explicitly required diff --git a/specs/README.md b/specs/README.md deleted file mode 100644 index 8ef221ac5..000000000 --- a/specs/README.md +++ /dev/null @@ -1,69 +0,0 @@ -# DTVM SSOT (Single Source of Truth) - -The authoritative source for all module specifications, architecture designs, and feature specifications in the DTVM project, following the Spec-Driven Development (SDD) methodology. - -## Project Overview - -DTVM (DeTerministic Virtual Machine) is a next-generation blockchain virtual machine built on WebAssembly (Wasm) while maintaining full Ethereum Virtual Machine (EVM) ABI compatibility. - -Key goals: -- Deterministic JIT execution with enhanced performance -- EVM ABI compatibility and multi-language ecosystem support -- TEE-native security and hardware-optimized efficiency -- AI-powered smart contract development through SmartCogent integration - -## Tech Stack - -- **Core Language**: C++ (C++17) -- **Runtime Support**: C, Rust APIs -- **Build System**: CMake -- **JIT Backend**: Customized implementation based on LLVM 15 -- **Target Architectures**: x86-64, ARM64 -- **Smart Contract Languages**: Solidity, C/C++, Rust, Java, Golang, AssemblyScript -- **Security**: Intel SGX TEE support -- **Testing**: CTest + Google Test, WebAssembly spec tests - -## Architecture Patterns - -- **Modular Design**: Independent adaptation layers for different instruction sets (Wasm, EVM, future RISC-V) -- **Unified IR**: All instruction sets translate to Deterministic Middle Intermediate Representation (dMIR) -- **Hybrid Execution**: Multiple execution modes with dynamic switching support -- **Plugin Architecture**: Extensible runtime system for different blockchain environments - -## Key Constraints - -- **Deterministic Execution**: All operations must be deterministic across platforms and runs -- **Gas Metering**: Precise resource consumption tracking for blockchain environments -- **Memory Safety**: Strict boundary checking and memory management -- **Cross-Platform**: Consistent behavior across x86-64 and ARM64 architectures -- **TEE Compatibility**: Minimal Trusted Computing Base (TCB) for SGX environments - -## Directory Structure - -``` -specs/ -├── README.md # This file - project SSOT overview -├── AGENTS.md # AI Agent behavior rules -├── architecture/ # Global architecture design -├── code-style/ # Coding style guidelines -├── testing/ # Testing guide -├── data-model/ # Global data model -├── modules/ # Module specifications (SSOT core) -├── features/ # Feature specifications (incremental development) -└── _archive/ # Archived completed features -``` - -## External Dependencies - -- **LLVM 15**: Required for multipass JIT compilation mode -- **CMake**: Build system and dependency management -- **WebAssembly Spec Tests**: Official compliance validation test suite -- **Intel SGX SDK**: Trusted execution environment support - -## Related Documentation - -- Build & Testing: [docs/start.md](../docs/start.md) -- User Guide: [docs/user-guide.md](../docs/user-guide.md) -- API Reference: [docs/API.md](../docs/API.md) -- Commit Convention: [docs/COMMIT_CONVENTION.md](../docs/COMMIT_CONVENTION.md) -- Versioning: [docs/VERSIONING.md](../docs/VERSIONING.md) diff --git a/specs/features/README.md b/specs/features/README.md deleted file mode 100644 index ff4d19ec8..000000000 --- a/specs/features/README.md +++ /dev/null @@ -1,18 +0,0 @@ -# Feature Specifications - -This directory stores feature specification documents for incremental development. Each feature uses the `NNN-short-name` numbering format. - -## Workflow - -1. Use `speckit-specify` to create the feature specification -2. Use `speckit-clarify` to clarify requirements -3. Use `speckit-plan` to generate technical design -4. Use `speckit-tasks` to generate task lists -5. Use `speckit-implement` to execute implementation -6. Upon completion, use `speckit-archive` to archive to `_archive/` - -## Notes - -- By default, no branches are created; feature specifications are created in `specs/features/` on the current branch -- Feature specifications should not duplicate module SSOT content; use reference links instead -- Each feature should be independently testable and deliverable