chore: consolidate spec/agent tooling and add skill mirror generation

.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.

.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/<YYYY-MM>/`.
+
+## 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-<slug>
+
+  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/<YYYY-MM>/` if it does not exist
+2. Move the change directory: `docs/changes/YYYY-MM-DD-<slug>/` to `docs/_archive/<YYYY-MM>/<slug>/`
+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 <branch-name>` (if merged)
+- **Worktree cleanup**: `git worktree remove <path>` (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

.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-<slug>/README.md`
+   - Light tier: copy `docs/changes/template-light.md` to `docs/changes/YYYY-MM-DD-<slug>/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/<module>/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