Restore commands key for 20 deterministic workflows

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Fixed
 - Migrate all 20 command files from `commands/` into `skills/` — completes the command-to-skill conversion started in v2.0.0
-- Remove `"commands"` key from `manifest.json` — all entries now under `"skills"`
+- Restore `"commands"` key in manifest for 20 deterministic workflows (tab-completable), keep `"skills"` for 14 context-activated entries — both point to `skills/` directory
 - Fix `manifest.json` version (was stuck at `1.3.5` while `plugin.json` was at `2.0.0`)
 - Remove duplicate `skills/` block in README repository structure
 - Fix orphaned `skill-authoring` reference in CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,33 +1,36 @@
 # Contributing to Devkit
 
-## Adding a Skill
+## Adding a Slash Command (deterministic workflow)
 
-1. Create `skills/my-skill.md` with YAML frontmatter:
+Slash commands appear in tab-completion and run step-by-step workflows.
+
+1. Create `skills/my-command.md` with YAML frontmatter:
    ```markdown
    ---
-   name: devkit:my-skill
-   description: One-line description.
+   name: devkit:my-command
+   description: What this command does.
    ---
-   # Skill Title
-   Body content (keep under 100 lines).
+   # Command Title
+   Step-by-step workflow with numbered steps.
    ```
-2. Add `"skills/my-skill.md"` to `manifest.json`
-3. See the "Adding an Invocable Skill" section below for full guidance
+2. Add `"skills/my-command.md"` to the `"commands"` array in `manifest.json`
+3. Include Budget & Early Exit section if the command loops
+4. Include `[PARALLEL]` markers if steps run concurrently
+
+## Adding a Context-Activated Skill
 
-## Adding an Invocable Skill (formerly "command")
+Skills activate automatically based on natural language — no slash command needed.
 
 1. Create `skills/my-skill.md` with YAML frontmatter:
    ```markdown
    ---
    name: devkit:my-skill
-   description: What this skill does.
+   description: Triggers on "natural language pattern".
    ---
    # Skill Title
-   Step-by-step workflow.
+   Guidelines or workflow (keep under 100 lines).
    ```
-2. Add `"skills/my-skill.md"` to `manifest.json`
-3. Include Budget & Early Exit section if the skill loops
-4. Include `[PARALLEL]` markers if steps run concurrently
+2. Add `"skills/my-skill.md"` to the `"skills"` array in `manifest.json`
 
 ## Adding an Agent
 

README.md

@@ -288,26 +288,35 @@ devkit/
 ├── manifest.json            # Plugin manifest
 ├── ROADMAP.md               # Implemented features and future plans
 ├── PREFERENCES.md           # Agent behavior guidelines
-├── skills/                  # Invocable + context-activated skills
-│   ├── tri-*.md             # Multi-agent skills (5)
+├── skills/                  # All skill files (commands + skills)
+│   │                        # — 20 slash commands (tab-completable) —
+│   ├── tri-*.md             # Multi-agent dispatch (5)
 │   ├── self-*.md            # Self-improvement loops (5)
 │   ├── pr-ready.md          # PR preparation pipeline
 │   ├── pr-monitor.md        # Post-PR review monitor
-│   ├── repo-map.md          # AST-based symbol index
-│   ├── audit.md             # Project health audit
-│   ├── workflow.md          # YAML workflow runner
-│   ├── feature.md           # Feature lifecycle
 │   ├── bugfix.md            # Bug fix lifecycle
+│   ├── feature.md           # Feature lifecycle
 │   ├── refactor.md          # Refactor lifecycle
 │   ├── decompose.md         # Goal decomposition
+│   ├── workflow.md          # YAML workflow runner
+│   ├── audit.md             # Project health audit
+│   ├── repo-map.md          # AST-based symbol index
 │   ├── status.md            # Health check
-│   ├── changelog.md         # Changelog generation
-│   ├── doc-gen.md           # Documentation generation
-│   ├── test-gen.md          # Test generation
-│   ├── research.md          # Deep research
-│   ├── scrape.md            # URL scraping
-│   ├── onboard.md           # Codebase onboarding
-│   └── ...                  # + context-activated skills
+│   │                        # — 14 context-activated skills —
+│   ├── executing.md         # Principle: methodical execution
+│   ├── clean-code.md        # Principle: readability
+│   ├── dry.md               # Principle: don't repeat yourself
+│   ├── yagni.md             # Principle: no speculative features
+│   ├── dont-reinvent.md     # Principle: use existing solutions
+│   ├── stuck.md             # Principle: loop recovery
+│   ├── creating-workflows.md # Tool: YAML workflow authoring
+│   ├── gcli.md              # Tool: Google Workspace CLI
+│   ├── changelog.md         # Auto: "generate a changelog"
+│   ├── doc-gen.md           # Auto: "document this module"
+│   ├── test-gen.md          # Auto: "write tests for X"
+│   ├── onboard.md           # Auto: "explain this codebase"
+│   ├── research.md          # Auto: "research X"
+│   └── scrape.md            # Auto: "scrape this URL"
 ├── agents/                  # 6 agents
 │   ├── reviewer.md          # Opus, worktree isolation
 │   ├── researcher.md        # Sonnet, worktree isolation

ROADMAP.md

@@ -3,7 +3,7 @@
 ## Implemented
 
 - **20 slash commands** — Lifecycle workflows, self-improvement loops, multi-agent dispatch, project health audit, post-PR monitoring, AST repo mapping
-- **14 skills** — 6 context-activated workflows (test-gen, doc-gen, changelog, onboard, research, scrape) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows)
+- **14 context-activated skills** — 6 auto-trigger workflows (test-gen, doc-gen, changelog, onboard, research, scrape) + 6 coding principles (executing, clean-code, DRY, YAGNI, dont-reinvent, stuck) + 2 tools (gcli, creating-workflows)
 - **6 agents** — Scoped tool access, worktree isolation, model assignment
 - **8 hooks** — Safety (destructive command blocking, edit-time security patterns, PR gate), observability (audit trail, slop detection, post-validation, subagent verification), optimization (RTK token compression)
 - **Graceful degradation** — tri:* commands work with 1-3 agents depending on installed CLIs

manifest.json

@@ -2,7 +2,7 @@
   "name": "devkit",
   "version": "2.0.1",
   "description": "Guardrails and consistency for Claude Code — deterministic workflows, metric-gated improvement loops, and multi-agent consensus",
-  "skills": [
+  "commands": [
     "skills/tri-review.md",
     "skills/tri-dispatch.md",
     "skills/tri-debug.md",
@@ -14,15 +14,17 @@
     "skills/self-perf.md",
     "skills/self-migrate.md",
     "skills/pr-ready.md",
+    "skills/pr-monitor.md",
     "skills/workflow.md",
     "skills/status.md",
     "skills/bugfix.md",
     "skills/feature.md",
     "skills/refactor.md",
     "skills/decompose.md",
     "skills/audit.md",
-    "skills/pr-monitor.md",
-    "skills/repo-map.md",
+    "skills/repo-map.md"
+  ],
+  "skills": [
     "skills/executing.md",
     "skills/clean-code.md",
     "skills/dry.md",

skills/tri-review.md

@@ -95,6 +95,10 @@ Input: {prompt}
 
 <!-- The orchestrator MUST inline the diff content here from /tmp/tri-review-diff.txt. The agent runs in a worktree and cannot fetch it. -->
 
+**IMPORTANT instruction to include in the Claude agent prompt:**
+
+> The diff above is the ONLY source of truth. Do NOT read files from the worktree to verify whether changes were applied — the worktree is based on main, not the PR branch, so files will appear unchanged. Review the diff as provided. If you need to check for stale references or orphan files, grep the worktree but understand that the diff's changes are NOT reflected there.
+
 ### Codex — if available
 
 **Plugin (preferred):**