codeforge-dev 1.12.0 → 1.14.1

package/.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/team/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: team
+description: >-
+  Guides agent team orchestration with TeamCreate, parallel teammate
+  spawning, task coordination, specialist agent selection, and
+  --teammate-mode configuration for concurrent workstreams. USE WHEN
+  the user asks to "spawn a team", "create a team of agents", "use a
+  swarm", "work in parallel", "coordinate multiple agents", "split this
+  across agents", "team up", or works with TeamCreate, SendMessage, and
+  multi-agent workflows. DO NOT USE for single-agent sequential tasks
+  where parallelism adds no value — a team requires 3+ independent
+  workstreams.
+version: 0.2.0
+disable-model-invocation: true
+---
+
+# Agent Team Orchestration
+
+## Mental Model
+
+A team is a group of specialist agents working in parallel under a lead (you). Each teammate runs independently with its own context — they share a task list but not conversation history. The lead decomposes work into parallel streams, spawns specialists, assigns tasks, and coordinates integration.
+
+Teams add value only when work can be parallelized. If every task depends on the previous one, a single agent is faster. The threshold: **3+ independent workstreams** that can run concurrently.
+
+```
+Lead (you)
+├── TeamCreate         → creates the team
+├── TaskCreate (×N)    → defines work units
+├── Task (×N)          → spawns specialist teammates
+├── TaskUpdate (×N)    → assigns tasks to teammates
+├── SendMessage        → coordinates during execution
+└── TeamDelete         → cleans up after completion
+```
+
+---
+
+## Two Modes
+
+Parse `$ARGUMENTS` for an optional `--now` flag to determine behavior:
+
+| Input | Mode | Behavior |
+|-------|------|----------|
+| `/team refactor the auth module` | Guidance | Absorb team knowledge, propose a plan, discuss with user |
+| `/team --now refactor the auth module` | Immediate | Create team, spawn agents, start work without waiting |
+| `/team` | Guidance | Ask the user what the team should accomplish |
+
+Strip `--now` from the purpose string before using it. Everything remaining is `<PURPOSE>`.
+
+### Guidance Mode (default — no `--now`)
+
+Inject the knowledge in this skill into context. **Do not force immediate action.** Analyze the purpose, propose a team composition, and discuss the approach with the user before acting. Use your judgment about when to create the team.
+
+### Immediate Mode (`--now` flag present)
+
+Act now without waiting for further input:
+
+1. **Analyze purpose** — determine workstreams and specialist roles needed
+2. **Create team** — `TeamCreate` with a kebab-case name derived from purpose
+3. **Create tasks** — `TaskCreate` for each work unit with dependencies via `TaskUpdate`
+4. **Spawn teammates** — `Task` with `team_name`, specialist `subagent_type`, descriptive `name`
+5. **Assign tasks** — `TaskUpdate` with `owner` set to each teammate's name
+6. **Coordinate** — monitor via `TaskList`, message via `SendMessage`
+7. **Shutdown** — `shutdown_request` to all teammates, then `TeamDelete`
+
+---
+
+## Team Lifecycle
+
+### 1. Create the Team
+
+```
+TeamCreate:
+  team_name: "auth-refactor"     # kebab-case, descriptive
+  description: "Refactor auth module for OAuth2 support"
+```
+
+One team per lead session. No nested teams.
+
+### 2. Create Tasks
+
+Each task should be independently completable by one agent:
+
+```
+TaskCreate:
+  subject: "Write unit tests for OAuth2 flow"          # imperative
+  description: "Full context the assignee needs..."     # self-contained
+  activeForm: "Writing OAuth2 unit tests"               # present continuous
+```
+
+Set ordering constraints with `TaskUpdate`:
+- `addBlockedBy: ["1"]` — this task waits for task 1
+- `addBlocks: ["3"]` — task 3 waits for this task
+
+### 3. Spawn Teammates
+
+Each teammate is spawned via the `Task` tool with `team_name`:
+
+```
+Task:
+  team_name: "auth-refactor"
+  subagent_type: "agent-system:test-writer"   # specialist agent type
+  name: "test-writer"                            # used for messaging and assignment
+  prompt: "All context needed for the work..."   # teammates have NO prior history
+```
+
+**Critical:** Teammates do not inherit your conversation. The spawn `prompt` must include every piece of context the teammate needs — file paths, requirements, constraints, conventions.
+
+### 4. Assign Tasks
+
+```
+TaskUpdate:
+  taskId: "2"
+  owner: "test-writer"    # matches the teammate's name
+```
+
+### 5. Coordinate
+
+- **Check progress:** `TaskList` shows all tasks with status and owner
+- **Direct message:** `SendMessage` with `type: "message"` and `recipient: "test-writer"`
+- **Broadcast:** `SendMessage` with `type: "broadcast"` — use ONLY for critical team-wide issues
+- **Idle is normal:** Teammates go idle after each turn. This is expected. Send a message to wake them.
+- **Quality gate hooks:** TeammateIdle and TaskCompleted hooks run automatically. TeammateIdle checks for incomplete tasks (exit 2 → teammate keeps working); TaskCompleted runs the test suite (exit 2 → task stays open). See agent-system plugin hooks.
+
+**In-process mode keyboard shortcuts:**
+
+| Shortcut | Action |
+|----------|--------|
+| `Shift+Down` | Cycle through teammates |
+| `Ctrl+T` | Toggle task list |
+| `Enter` | View a teammate's session |
+| `Escape` | Interrupt teammate's current turn |
+
+> **Tip:** Use `claude --teammate-mode in-process` for per-session display mode override. Configure permanently via `teammateMode` in settings.json.
+
+### 5a. Plan Approval
+
+When `CLAUDE_CODE_PLAN_MODE_REQUIRED` is `true` (current setting), teammates run in read-only plan mode until the lead approves their plan.
+
+**Workflow:**
+1. Teammate enters plan mode → creates an implementation plan
+2. Lead receives `plan_approval_request` message with the plan
+3. Lead reviews the plan and sends `plan_approval_response` (approve or reject)
+4. On approval → teammate exits plan mode and implements
+5. On rejection → teammate stays in plan mode, revises, resubmits
+
+**Influencing plans:** Include criteria in the spawn `prompt` to shape what the lead should look for (e.g., "only approve plans that include test coverage", "reject plans that modify shared utilities without coordination").
+
+### 6. Shutdown
+
+When all tasks are complete:
+
+1. Send `shutdown_request` to each teammate via `SendMessage`
+2. Wait for confirmations
+3. `TeamDelete` to remove team and task directories
+4. Report results to the user
+
+---
+
+## Specialist Agent Types
+
+Choose the agent whose domain matches the work. **Generalist is a last resort.**
+
+| Agent Type | Domain | Capabilities |
+|-----------|--------|-------------|
+| `researcher` | Codebase & web research | Read-only |
+| `test-writer` | Write test suites | Read + Write + Bash |
+| `refactorer` | Safe code transformations | Read + Write + Bash |
+| `doc-writer` | README, API docs, docstrings | Read + Write |
+| `migrator` | Framework upgrades, version bumps | Read + Write + Bash |
+| `security-auditor` | OWASP audit, secrets scan | Read-only |
+| `git-archaeologist` | Git history investigation | Read-only + Bash |
+| `dependency-analyst` | Outdated/vulnerable deps | Read-only + Bash |
+| `spec-writer` | Requirements & acceptance criteria | Read-only |
+| `perf-profiler` | Profiling & benchmarks | Read-only + Bash |
+| `debug-logs` | Log analysis & diagnostics | Read-only + Bash |
+| `architect` | Implementation planning | Read-only |
+| `explorer` | Fast codebase search | Read-only |
+| `generalist` | Multi-step tasks (last resort) | All tools |
+| `bash-exec` | Command execution | Bash only |
+
+Prefix with `agent-system:` when spawning (e.g., `agent-system:test-writer`).
+
+---
+
+## Use Cases
+
+**Parallel code review** — split review criteria into independent domains (security, performance, test coverage). Each reviewer focuses on one lens, reducing blind spots.
+
+**Competing hypotheses** — adversarial investigation where teammates explore different theories about a bug or design decision. Each builds evidence for their hypothesis; lead synthesizes findings.
+
+**Cross-layer coordination** — frontend, backend, and tests each owned by a different teammate. Clear file ownership prevents conflicts; integration points are managed by the lead.
+
+**Research sweep** — parallel investigation of libraries, APIs, or approaches. Each researcher covers one option; lead compares findings and makes the selection.
+
+---
+
+## Team Composition Examples
+
+| Purpose | Recommended Team |
+|---------|-----------------|
+| Feature build | `researcher` + `test-writer` + `doc-writer` |
+| Security hardening | `security-auditor` + `dependency-analyst` |
+| Codebase cleanup | `refactorer` + `test-writer` |
+| Migration project | `researcher` + `migrator` |
+| Performance work | `perf-profiler` + `refactorer` |
+| Full-stack feature | `architect` + `generalist` (backend) + `generalist` (frontend) + `test-writer` |
+| Code audit | `security-auditor` + `dependency-analyst` + `perf-profiler` |
+| Documentation sprint | `researcher` + `doc-writer` |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| More than 5 teammates | Coordination overhead outweighs parallelism | Limit to 2–5, matching actual parallel workstreams |
+| Same-file edits by two agents | Merge conflicts are unrecoverable | Assign file ownership — one agent per file |
+| Sequential-only work | Team adds overhead with zero parallel benefit | Use a single agent |
+| Generalist everywhere | Specialists carry domain knowledge and safety hooks | Pick the specialist whose domain matches |
+| Empty spawn prompts | Teammates have no prior context | Include all requirements, file paths, conventions |
+| Skipping shutdown | Orphaned agents consume resources | Always send `shutdown_request` + `TeamDelete` |
+| Broadcasting for routine updates | Each broadcast = N messages (one per teammate) | Use direct `message` to specific teammates |
+
+---
+
+## Best Practices
+
+- **Give teammates enough context** — they don't inherit conversation history. The spawn `prompt` must be self-contained: include file paths, requirements, constraints, and project conventions.
+- **Size tasks appropriately** — too small = coordination overhead exceeds benefit; too large = work too long without check-ins. Aim for self-contained units producing clear deliverables, roughly 5-6 tasks per teammate.
+- **Wait for teammates to finish** — leads sometimes start implementing work that teammates are handling. If you notice this, redirect yourself to monitoring and coordination.
+- **Start with research and review** — for first-time team use, prefer tasks with clear boundaries that don't require code changes: reviewing PRs, researching libraries, investigating bugs.
+- **Monitor and steer** — check progress via `TaskList`, redirect failing approaches, synthesize findings. Unattended teams risk wasted effort.
+- **Avoid file conflicts** — break work so each teammate owns different files. Agents with `isolation: worktree` (test-writer, refactorer, doc-writer, migrator) get automatic file isolation via git worktrees.
+
+---
+
+## Limitations
+
+- **No session resumption** — `/resume` does not restore in-process teammates. Plan team work to complete in one session.
+- **Task status can lag** — teammates sometimes fail to mark tasks complete. Use `TaskList` to verify and `SendMessage` to prompt updates.
+- **One team per session** — clean up the current team (`TeamDelete`) before starting a new one.
+- **No nested teams** — teammates cannot create teams (TeamCreate/TeamDelete are disallowed for team members).
+- **Lead is fixed** — leadership cannot be promoted or transferred during a session.
+- **Permissions set at spawn** — all teammates inherit the lead's permission mode at spawn time.
+- **Split panes require tmux or iTerm2** — in-process mode uses the terminal; external split-pane workflows need tmux or iTerm2 with `it2` CLI.
+
+---
+
+## Tool Reference
+
+| Tool | Purpose | Key Parameters |
+|------|---------|---------------|
+| `TeamCreate` | Create the team | `team_name`, `description` |
+| `Task` | Spawn teammate into team | `team_name`, `subagent_type`, `name`, `prompt` |
+| `TaskCreate` | Add task to shared list | `subject`, `description`, `activeForm` |
+| `TaskUpdate` | Assign, depend, complete | `taskId`, `owner`, `status`, `addBlockedBy` |
+| `TaskList` | View all tasks and status | (none) |
+| `TaskGet` | Read full task details | `taskId` |
+| `SendMessage` | Communicate with teammates | `type`, `recipient`, `content`, `summary` |
+| `TeamDelete` | Clean up after completion | (none) |
+
+---
+
+## Ambiguity Policy
+
+- If `$ARGUMENTS` is empty (no purpose provided), ask: "What should the team accomplish?"
+- If the purpose maps to a single workstream with no parallelism, advise against a team and offer to do the work directly.
+- If unsure which specialists to pick, present 2–3 composition options with trade-offs and let the user choose.
+- If the purpose is vague ("make the app better"), ask for specifics before composing a team.
+- If a teammate reports a blocker, attempt to resolve it yourself or reassign the task before escalating to the user.
+- In immediate mode, default to the most natural team composition. If genuinely ambiguous, fall back to guidance mode and ask.

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → skill-engine}/skills/testing/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: testing
 description: >-
-  This skill should be used when the user asks to "write tests for a FastAPI endpoint",
-  "test a Svelte component", "set up pytest fixtures for FastAPI",
-  "configure Vitest for SvelteKit", "mock dependencies in FastAPI tests",
-  "test SSE streaming endpoints", "write component tests with Testing Library",
-  "set up database fixtures for API tests", or discusses pytest, httpx AsyncClient,
-  Vitest, @testing-library/svelte, dependency overrides, or test fixtures.
-version: 0.1.0
+  Provides testing patterns for FastAPI endpoints and Svelte 5 components
+  using pytest and Vitest. USE WHEN the user asks to "write tests for a
+  FastAPI endpoint", "test a Svelte component", "set up pytest fixtures",
+  "configure Vitest for SvelteKit", "mock dependencies in tests", "test SSE
+  streaming endpoints", or works with pytest, httpx AsyncClient, Vitest,
+  @testing-library/svelte, MSW, pytest-anyio. DO NOT USE for general testing
+  theory unrelated to FastAPI or Svelte.
+version: 0.2.0
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: "[file or module]"
 ---
 
 # Testing (FastAPI + Svelte)

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+	"name": "spec-workflow",
+	"description": "Specification lifecycle management: creation, refinement, building, reviewing, updating, and auditing",
+	"author": {
+		"name": "AnExiledDev"
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/README.md

@@ -0,0 +1,192 @@
+# spec-workflow
+
+Claude Code plugin that manages the full specification lifecycle: creating, refining, building, reviewing, updating, and auditing feature specs. Includes an advisory hook that reminds about spec updates when code changes but specs don't.
+
+## What It Does
+
+Two capabilities:
+
+1. **Spec lifecycle skills** — 8 skills that cover the complete journey from bootstrapping a `.specs/` directory to closing out an as-built spec after implementation.
+
+2. **Spec reminder hook** — A `Stop` hook that fires when source code was modified but no `.specs/` files were updated, advising Claude to run `/spec-update`.
+
+### Skill Catalog
+
+| Skill | Slash Command | Purpose |
+|-------|---------------|---------|
+| spec-init | `/spec-init` | Bootstrap `.specs/` directory with BACKLOG.md, MILESTONES.md, ROADMAP.md |
+| spec-new | `/spec-new` | Create a new feature spec from EARS template |
+| spec-refine | `/spec-refine` | Validate assumptions with user, upgrade requirements to `[user-approved]` |
+| spec-build | `/spec-build` | Orchestrate full implementation: plan, build, review, close |
+| spec-check | `/spec-check` | Audit all specs for health issues |
+| spec-review | `/spec-review` | Verify implementation against a spec |
+| spec-update | `/spec-update` | As-built closure: update spec to match implementation |
+| specification-writing | `/skill specification-writing` | Domain knowledge for writing high-quality specs |
+
+### Spec Lifecycle
+
+```
+/spec-init          Bootstrap .specs/ directory
+     |
+/spec-new           Create feature spec (draft, [assumed] requirements)
+     |
+/spec-refine        Validate with user -> [user-approved] requirements
+     |
+/spec-build         5-phase implementation orchestration:
+     |                Phase 1: Discovery
+     |                Phase 2: Planning
+     |                Phase 3: Building ([ ] -> [~])
+     |                Phase 4: Review   ([~] -> [x])
+     |                Phase 5: Closure  (as-built update)
+     |
+/spec-review        Standalone verification (post-change audits)
+     |
+/spec-update        Manual as-built closure
+     |
+/spec-check         Health audit across all specs
+```
+
+### Acceptance Criteria Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[ ]` | Not started |
+| `[~]` | Implemented, not yet verified |
+| `[x]` | Verified — tests pass, behavior confirmed |
+
+### Approval and Requirement Tags
+
+- `**Approval:** draft` — Spec is in draft, not ready for implementation
+- `**Approval:** user-approved` — Spec reviewed and approved by user
+- `[assumed]` — Requirement inferred by Claude, needs validation
+- `[user-approved]` — Requirement explicitly approved by user
+
+## How It Works
+
+### Hook Lifecycle
+
+```
+Claude stops responding (Stop event)
+  |
+  +-> Stop fires
+        |
+        +-> spec-reminder.py
+              |
+              +-> .specs/ directory exists?
+              |     |
+              |     +-> No -> Silent exit (no output)
+              |     +-> Yes -> Continue
+              |
+              +-> Source code modified this session?
+              |     |
+              |     +-> No -> Silent exit
+              |     +-> Yes -> Continue
+              |
+              +-> .specs/ files also modified?
+                    |
+                    +-> Yes -> Silent exit (already updated)
+                    +-> No -> Inject advisory: "Run /spec-update"
+```
+
+### Monitored Source Directories
+
+The spec reminder watches for changes in these directories:
+
+`src/`, `lib/`, `app/`, `pkg/`, `internal/`, `cmd/`, `tests/`, `api/`, `frontend/`, `backend/`, `packages/`, `services/`, `components/`, `pages/`, `routes/`
+
+### Exit Code Behavior
+
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | Advisory injected (or silent — no action needed) |
+
+The hook never blocks operations.
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| No `.specs/` directory | Silent exit |
+| Not a git repository | Silent exit |
+| JSON parse failure | Silent exit |
+
+### Timeouts
+
+| Hook | Timeout |
+|------|---------|
+| Spec reminder (Stop) | 8s |
+
+## Installation
+
+### CodeForge DevContainer
+
+Pre-installed and activated automatically — no setup needed.
+
+### From GitHub
+
+Use this plugin in any Claude Code setup:
+
+1. Clone the [CodeForge](https://github.com/AnExiledDev/CodeForge) repository:
+
+   ```bash
+   git clone https://github.com/AnExiledDev/CodeForge.git
+   ```
+
+2. Enable the plugin in your `.claude/settings.json`:
+
+   ```json
+   {
+     "enabledPlugins": {
+       "spec-workflow@<clone-path>/.devcontainer/plugins/devs-marketplace": true
+     }
+   }
+   ```
+
+   Replace `<clone-path>` with the absolute path to your CodeForge clone.
+
+## Plugin Structure
+
+```
+spec-workflow/
++-- .claude-plugin/
+|   +-- plugin.json                     # Plugin metadata
++-- hooks/
+|   +-- hooks.json                      # Stop hook registration
++-- scripts/
+|   +-- spec-reminder.py                # Spec update advisory (Stop)
++-- skills/
+|   +-- spec-init/                      # Bootstrap .specs/ directory
+|   |   +-- SKILL.md
+|   |   +-- references/
+|   |       +-- backlog-template.md
+|   |       +-- milestones-template.md
+|   |       +-- roadmap-template.md
+|   +-- spec-new/                       # Create new feature spec
+|   |   +-- SKILL.md
+|   |   +-- references/
+|   |       +-- template.md
+|   +-- spec-refine/                    # Validate assumptions with user
+|   |   +-- SKILL.md
+|   +-- spec-build/                     # Full implementation orchestration
+|   |   +-- SKILL.md
+|   |   +-- references/
+|   |       +-- review-checklist.md
+|   +-- spec-check/                     # Spec health audit
+|   |   +-- SKILL.md
+|   +-- spec-review/                    # Implementation verification
+|   |   +-- SKILL.md
+|   +-- spec-update/                    # As-built closure
+|   |   +-- SKILL.md
+|   +-- specification-writing/          # Domain knowledge skill
+|       +-- SKILL.md
+|       +-- references/
+|           +-- criteria-patterns.md
+|           +-- ears-templates.md
++-- README.md                           # This file
+```
+
+## Requirements
+
+- Python 3.11+
+- Git (for detecting file changes)
+- Claude Code with plugin hook support (skills)

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+	"description": "Spec reminder advisory when code is modified but specs are not updated",
+	"hooks": {
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/spec-reminder.py",
+						"timeout": 8
+					}
+				]
+			}
+		]
+	}
+}

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → spec-workflow}/scripts/spec-reminder.py

@@ -9,7 +9,8 @@ Injects an advisory reminder as additionalContext pointing the user to
 Only fires when a .specs/ directory exists (project uses the spec system).
 
 Reads hook input from stdin (JSON). Returns JSON on stdout.
-Always exits 0 (advisory, never blocking).
+Blocks with decision/reason so Claude addresses the spec gap
+before finishing. The stop_hook_active guard prevents infinite loops.
 """
 
 import json
@@ -115,7 +116,7 @@ def main():
         "or /spec-refine if the spec is still in draft status."
     )
 
-    json.dump({"additionalContext": message}, sys.stdout)
+    json.dump({"decision": "block", "reason": message}, sys.stdout)
     sys.exit(0)
 
 

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → spec-workflow}/skills/spec-build/SKILL.md

@@ -1,12 +1,15 @@
 ---
 name: spec-build
 description: >-
-  This skill should be used when the user asks to "implement the spec",
-  "build from spec", "start building the feature", "spec-build",
-  "implement this feature from the spec", "build what the spec describes",
-  or needs to orchestrate full implementation of an approved specification
-  through a phased workflow of planning, building, reviewing, and closing.
-version: 0.1.0
+  Orchestrates full implementation of an approved specification through
+  5 phases: discovery, planning, building, review, and closure. USE WHEN
+  the user asks to "implement the spec", "build from spec", "start building
+  the feature", "implement this feature", "build what the spec describes",
+  "run spec-build", or works with phased implementation workflows.
+  DO NOT USE for creating, refining, or updating specs — use spec-new,
+  spec-refine, or spec-update instead.
+version: 0.2.0
+argument-hint: "[spec-path]"
 ---
 
 # Spec-Driven Implementation

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → spec-workflow}/skills/spec-check/SKILL.md

@@ -1,11 +1,16 @@
 ---
 name: spec-check
 description: >-
-  This skill should be used when the user asks to "check spec status",
-  "audit specs", "which specs are stale", "spec health", "find missing
-  specs", "review spec quality", or needs a comprehensive audit of all
-  specifications in the project.
-version: 0.1.0
+  Audits all specifications in a project for health issues including stale
+  status, missing sections, unapproved drafts, and assumed requirements.
+  USE WHEN the user asks to "check spec health", "audit specs", "which
+  specs are stale", "find missing specs", "review spec quality",
+  "run spec-check", "are my specs up to date", or works with .specs/
+  directory maintenance and specification metadata.
+  DO NOT USE for single-spec code review or implementation verification
+  — use spec-review for deep code-level audits against one spec.
+version: 0.2.0
+argument-hint: "[domain or path]"
 context: fork
 agent: explorer
 ---

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → spec-workflow}/skills/spec-init/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: spec-init
 description: >-
-  This skill should be used when the user asks to "initialize specs",
-  "set up specs", "bootstrap specs", "start using specs", "create spec
-  directory", "init specs for this project", or needs to set up the
-  .specs/ directory structure for a project that doesn't have one yet.
+  Bootstraps the .specs/ directory structure for a project, creating
+  MILESTONES.md and BACKLOG.md from starter templates so spec-new has
+  a home. USE WHEN the user asks to "initialize specs", "set up specs",
+  "bootstrap specs", "start using specs", "create spec directory",
+  "init specs for this project", "set up .specs", or works with first-
+  time specification setup and project onboarding.
+  DO NOT USE if .specs/ already exists — use spec-check to audit health
+  or spec-new to add individual specs.
 version: 0.2.0
 ---
 

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/spec-init/references/roadmap-template.md

@@ -0,0 +1,33 @@
+# Roadmap
+
+> Features live in the priority-graded backlog until pulled into a version.
+> Versions are scoped and spec'd when ready to build — not pre-assigned.
+> See `BACKLOG.md` for the feature backlog.
+
+## How Versioning Works
+
+1. **Backlog** — All desired features live in `BACKLOG.md`, graded by priority.
+2. **Version scoping** — When ready to start a new version, pull features from the backlog.
+3. **Spec first** — Each feature in a version gets a spec before implementation begins.
+4. **Ship** — Version is done when all its specs are implemented and verified.
+
+Only the **next version** is defined in detail. Everything else is backlog.
+
+## Released
+
+_None yet._
+
+## Current
+
+### v0.1.0 — [Name] 🔧
+
+- [ ] [Feature pulled from backlog]
+- [ ] [Feature pulled from backlog]
+
+## Next
+
+> Scoped from `BACKLOG.md` when current version is complete.
+
+## Out of Scope
+
+- [Items explicitly not planned]

package/.devcontainer/plugins/devs-marketplace/plugins/{code-directive → spec-workflow}/skills/spec-new/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: spec-new
 description: >-
-  This skill should be used when the user asks to "create a spec",
-  "new feature spec", "write a spec for", "spec this feature",
-  "start a new spec", "plan a feature", or needs to create a new
-  specification file from the standard template.
+  Creates a new feature specification from the standard EARS template
+  with domain inference, acceptance criteria, and requirement tagging.
+  USE WHEN the user asks to "create a spec", "new feature spec", "write
+  a spec for", "spec this feature", "start a new spec", "plan a feature",
+  "add a spec", or works with .specs/ directory and feature planning.
+  DO NOT USE for updating existing specs after implementation — use
+  spec-update instead. Not for refining draft specs — use spec-refine.
 version: 0.2.0
+argument-hint: "[feature-name] [domain]"
 ---
 
 # Create New Feature Specification