codeforge-dev 1.13.0 → 1.14.1

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

@@ -3,7 +3,6 @@
 	"hooks": {
 		"Stop": [
 			{
-				"matcher": "",
 				"hooks": [
 					{
 						"type": "command",

package/.devcontainer/plugins/devs-marketplace/plugins/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/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/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/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-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

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/spec-refine/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: spec-refine
 description: >-
-  This skill should be used when the user asks to "refine a spec",
-  "review spec assumptions", "validate spec decisions", "question the
-  spec", "iterate on the spec", "check spec for assumptions", "approve
-  the spec", "walk me through the spec", or needs iterative
-  user-driven refinement of a specification through structured
-  questioning rounds.
-version: 0.1.0
+  Guides iterative user-driven spec refinement through structured
+  questioning rounds that validate assumptions, tech decisions, and scope
+  boundaries. USE WHEN the user asks to "refine the spec", "review spec
+  assumptions", "validate spec decisions", "approve the spec", "walk me
+  through the spec", "check spec for assumptions", "iterate on the spec",
+  or works with [assumed] requirements needing user-approved upgrade.
+  DO NOT USE for creating new specs (use spec-new) or for post-
+  implementation updates (use spec-update).
+version: 0.2.0
+argument-hint: "[spec-path]"
 ---
 
 # Iterative Spec Refinement

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/spec-review/SKILL.md

@@ -1,12 +1,16 @@
 ---
 name: spec-review
 description: >-
-  This skill should be used when the user asks to "review the spec",
-  "check spec adherence", "verify implementation", "spec-review",
-  "does code match spec", "audit implementation", or needs a standalone
-  deep implementation review that reads the code and confirms full
-  adherence to a specification.
-version: 0.1.0
+  Performs a standalone deep implementation review by reading code and
+  verifying full adherence to a specification's requirements and acceptance
+  criteria. USE WHEN the user asks to "review the spec", "verify
+  implementation", "does code match spec", "audit implementation",
+  "check spec adherence", "run spec-review", "regression check", or
+  works with post-implementation verification and pre-release audits.
+  DO NOT USE for batch metadata audits across all specs (use spec-check)
+  or for updating spec status after review (use spec-update).
+version: 0.2.0
+argument-hint: "[spec-path]"
 ---
 
 # Spec Implementation Review

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/spec-update/SKILL.md

@@ -1,11 +1,16 @@
 ---
 name: spec-update
 description: >-
-  This skill should be used when the user asks to "update the spec",
-  "mark spec as implemented", "as-built update", "spec maintenance",
-  "update spec status", "finish the spec", or after implementing a
-  feature when the spec needs to reflect what was actually built.
-version: 0.1.0
+  Performs the as-built spec update after implementation, closing the loop
+  between what was planned and what was built by setting status, checking
+  off acceptance criteria, and adding implementation notes. USE WHEN the
+  user asks to "update the spec", "mark spec as implemented", "as-built
+  update", "finish the spec", "close the spec", "update spec status",
+  "sync spec with code", or works with post-implementation documentation.
+  DO NOT USE for verifying code against a spec (use spec-review first)
+  or for creating new specs (use spec-new).
+version: 0.2.0
+argument-hint: "[spec-path]"
 ---
 
 # As-Built Spec Update

package/.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/specification-writing/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: specification-writing
 description: >-
-  This skill should be used when the user asks to "write a specification",
-  "create requirements", "define acceptance criteria", "write user stories",
-  "create a feature spec", "document requirements", "use EARS format",
-  "write Given/When/Then scenarios", "define edge cases for a feature",
-  "structure a product requirement document",
-  or discusses requirement formats, EARS templates, Gherkin syntax,
-  acceptance criteria patterns, specification structure,
-  or completeness checklists for feature definitions.
-version: 0.1.0
+  Teaches EARS requirement formats, Given/When/Then acceptance criteria,
+  and structured specification patterns for feature definitions. USE WHEN
+  the user asks to "write requirements", "use EARS format", "define
+  acceptance criteria", "write Given/When/Then scenarios", "create a
+  feature spec", "structure requirements", "write user stories", or works
+  with Gherkin syntax, FR/NFR numbering, and completeness checklists.
+  DO NOT USE for managing the spec lifecycle (create, refine, build,
+  review, update) — use the dedicated spec-* skills instead.
+version: 0.2.0
 ---
 
 # Specification Writing

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

@@ -3,6 +3,5 @@
   "description": "EARS-based ticket workflow: create issues, plan implementation, review commits, create PRs",
   "author": {
     "name": "AnExiledDev"
-  },
-  "keywords": ["tickets", "github", "workflow", "ears", "issues", "pr"]
+  }
 }

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

@@ -74,6 +74,34 @@ Each ticket created by `/ticket:new` includes:
 
 The plugin injects a system prompt that defines the assistant persona, coding standards (SOLID, DRY, KISS, YAGNI), testing standards, and the ticket workflow rules. This ensures consistent behavior across all four commands.
 
+## 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": {
+       "ticket-workflow@<clone-path>/.devcontainer/plugins/devs-marketplace": true
+     }
+   }
+   ```
+
+   Replace `<clone-path>` with the absolute path to your CodeForge clone.
+
 ## Plugin Structure
 
 ```

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

@@ -3,7 +3,6 @@
 	"hooks": {
 		"UserPromptSubmit": [
 			{
-				"matcher": "*",
 				"hooks": [
 					{
 						"type": "command",

package/.devcontainer/plugins/devs-marketplace/plugins/ticket-workflow/scripts/ticket-linker.py

@@ -129,7 +129,15 @@ def main():
     if len(output) > TOTAL_OUTPUT_CAP:
         output = output[:TOTAL_OUTPUT_CAP] + "\n...(truncated)"
 
-    json.dump({"additionalContext": output}, sys.stdout)
+    json.dump(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": output,
+            }
+        },
+        sys.stdout,
+    )
     sys.exit(0)