codeforge-dev 1.8.0 → 1.9.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/scripts/spec-reminder.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""
+Spec reminder — Stop hook that advises about spec updates after code changes.
+
+On Stop, checks if source code was modified but no .specs/ files were updated.
+Injects an advisory reminder as additionalContext pointing the user to
+/spec-update.
+
+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).
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+GIT_CMD_TIMEOUT = 5
+
+# Directories whose changes should trigger the spec reminder
+CODE_DIRS = (
+    "src/",
+    "lib/",
+    "app/",
+    "pkg/",
+    "internal/",
+    "cmd/",
+    "tests/",
+    "api/",
+    "frontend/",
+    "backend/",
+    "packages/",
+    "services/",
+    "components/",
+    "pages/",
+    "routes/",
+)
+
+
+def _run_git(args: list[str]) -> str | None:
+    """Run a git command and return stdout, or None on any failure."""
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+            timeout=GIT_CMD_TIMEOUT,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    # Skip if another Stop hook is already blocking
+    if input_data.get("stop_hook_active"):
+        sys.exit(0)
+
+    cwd = os.getcwd()
+
+    # Only fire if this project uses the spec system
+    if not os.path.isdir(os.path.join(cwd, ".specs")):
+        sys.exit(0)
+
+    # Get all changed files (staged + unstaged)
+    diff_output = _run_git(["diff", "--name-only", "HEAD"])
+    staged_output = _run_git(["diff", "--name-only", "--cached"])
+
+    # Also include untracked files in source dirs
+    untracked = _run_git(["ls-files", "--others", "--exclude-standard"])
+
+    all_files: set[str] = set()
+    for output in (diff_output, staged_output, untracked):
+        if output:
+            all_files.update(output.splitlines())
+
+    if not all_files:
+        sys.exit(0)
+
+    # Check if any code directories have changes
+    has_code_changes = any(f.startswith(d) for f in all_files for d in CODE_DIRS)
+
+    if not has_code_changes:
+        sys.exit(0)
+
+    # Check if any spec files were also changed
+    has_spec_changes = any(f.startswith(".specs/") for f in all_files)
+
+    if has_spec_changes:
+        # Specs were updated alongside code — no reminder needed
+        sys.exit(0)
+
+    # Code changed but specs didn't — inject reminder
+    code_dirs_touched = sorted(
+        {f.split("/")[0] + "/" for f in all_files if "/" in f}
+        & {d.rstrip("/") + "/" for d in CODE_DIRS}
+    )
+    dirs_str = ", ".join(code_dirs_touched[:3])
+
+    message = (
+        f"[Spec Reminder] Code was modified in {dirs_str} "
+        "but no specs were updated. "
+        "Use /spec-update to update the relevant spec, "
+        "or /spec-new if no spec exists for this feature."
+    )
+
+    json.dump({"additionalContext": message}, sys.stdout)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-check/SKILL.md

@@ -0,0 +1,86 @@
+---
+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
+context: fork
+agent: explorer
+---
+
+# Spec Health Audit
+
+Audit all specifications in the current project and report their health status.
+
+## Workflow
+
+### Step 1: Discover Specs
+
+```
+Glob: .specs/**/*.md
+```
+
+If `.specs/` does not exist, report: "No specification directory found. Use `/spec-new` to create your first spec."
+
+Exclude non-spec files:
+- `ROADMAP.md`
+- `BACKLOG.md`
+- `LESSONS_LEARNED.md`
+- Files in `archive/`
+- `_overview.md` files (report them separately as parent specs)
+
+### Step 2: Read Each Spec
+
+For each spec file, extract:
+- **Feature name** from the `# Feature: [Name]` header
+- **Version** from the `**Version:**` field
+- **Status** from the `**Status:**` field
+- **Last Updated** from the `**Last Updated:**` field
+- **Line count** (wc -l)
+- **Sections present** — check for each required section header
+- **Acceptance criteria** — count total, count checked `[x]`
+- **Discrepancies** — check if section has content
+
+### Step 3: Flag Issues
+
+For each spec, check these conditions:
+
+| Issue | Condition | Severity |
+|-------|-----------|----------|
+| **Stale** | Status is `planned` but Last Updated is >30 days ago | High |
+| **Incomplete** | Missing required sections (Intent, Acceptance Criteria, Key Files, Requirements, Out of Scope) | High |
+| **Oversized** | Exceeds 200 lines | Medium |
+| **No criteria** | Acceptance Criteria section is empty or has no checkboxes | High |
+| **Open discrepancies** | Discrepancies section has content | Medium |
+| **Missing as-built** | Status is `implemented` but Implementation Notes is empty | Medium |
+| **Stale paths** | Key Files references paths that don't exist | Low |
+
+### Step 4: Report
+
+Output a summary table:
+
+```
+## Spec Health Report
+
+| Feature | Version | Status | Updated | Lines | Issues |
+|---------|---------|--------|---------|-------|--------|
+| Session History | v0.2.0 | implemented | 2026-02-08 | 74 | None |
+| Auth Flow | v0.3.0 | planned | 2026-01-15 | 45 | Stale (26 days) |
+| Settings Page | v0.2.0 | partial | 2026-02-05 | 210 | Oversized |
+
+## Issues Found
+
+### High Priority
+- **Auth Flow** (`.specs/v0.3.0/auth-flow.md`): Status is `planned` but last updated 26 days ago. Either implementation is stalled or the spec needs an as-built update.
+
+### Medium Priority
+- **Settings Page** (`.specs/v0.2.0/settings-page.md`): 210 lines exceeds the 200-line limit. Split into sub-specs.
+
+### Suggested Actions
+1. Run `/spec-update auth-flow` to update the auth flow spec
+2. Split settings-page.md into sub-specs
+```
+
+If no issues are found, report: "All specs healthy. N specs across M versions."

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/SKILL.md

@@ -0,0 +1,97 @@
+---
+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.
+version: 0.1.0
+---
+
+# Initialize Specification Directory
+
+## Mental Model
+
+Before any spec can be created, the project needs a `.specs/` directory with its supporting files: a ROADMAP (what each version delivers) and a BACKLOG (deferred items). This skill bootstraps that structure so `/spec-new` has a home.
+
+---
+
+## Workflow
+
+### Step 1: Check Existing State
+
+```
+Glob: .specs/**/*.md
+```
+
+**If `.specs/` already exists:**
+- Report current state: how many specs, versions, whether ROADMAP.md and BACKLOG.md exist
+- Suggest `/spec-check` to audit health instead
+- Do NOT recreate or overwrite anything
+- Stop here
+
+**If `.specs/` does not exist:** proceed to Step 2.
+
+### Step 2: Create Directory Structure
+
+Create the `.specs/` directory at the project root.
+
+### Step 3: Create ROADMAP.md
+
+Write `.specs/ROADMAP.md` using the template from `references/roadmap-template.md`.
+
+### Step 4: Create BACKLOG.md
+
+Write `.specs/BACKLOG.md` using the template from `references/backlog-template.md`.
+
+### Step 5: Retroactive Documentation
+
+Ask the user:
+
+> "Are there existing features in this project that should be documented retroactively? I can help create specs for them using `/spec-new`."
+
+If yes, guide the user through creating a spec for each feature using `/spec-new`.
+
+If no, proceed to Step 6.
+
+### Step 6: Report
+
+Summarize what was created:
+
+```
+## Spec Directory Initialized
+
+Created:
+- `.specs/` directory
+- `.specs/ROADMAP.md` — version tracking table
+- `.specs/BACKLOG.md` — deferred items list
+
+Next steps:
+- Use `/spec-new <feature-name> <version>` to create your first feature spec
+- Use `/spec-check` to audit spec health at any time
+```
+
+---
+
+## Hard Constraints
+
+- **Never overwrite** an existing `.specs/` directory or its contents.
+- **ROADMAP.md** must stay under 30 lines (it's a summary, not a plan document).
+- **BACKLOG.md** must stay under 15 lines (it grows as items are added).
+- Templates are starting points — the user will extend them.
+
+---
+
+## Ambiguity Policy
+
+- If the user runs this in a workspace root with multiple projects, ask which project to initialize.
+- If `.specs/` exists but is missing ROADMAP.md or BACKLOG.md, offer to create only the missing files.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/roadmap-template.md` | Starter ROADMAP with version table format |
+| `references/backlog-template.md` | Starter BACKLOG with item format |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/backlog-template.md

@@ -0,0 +1,7 @@
+# Backlog
+
+Deferred items not yet scheduled for a version.
+
+## Items
+
+- [ ] [Item description] — [context/rationale]

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

@@ -0,0 +1,13 @@
+# Roadmap
+
+What each version delivers and why.
+
+| Version | Status | Summary |
+|---------|--------|---------|
+| v0.1.0  | planned | [Initial release — describe core features] |
+
+## Versioning
+
+- **Major**: Breaking changes to public APIs or data models
+- **Minor**: New features, non-breaking changes
+- **Patch**: Bug fixes, documentation, internal refactors

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/SKILL.md

@@ -0,0 +1,101 @@
+---
+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.
+version: 0.1.0
+---
+
+# Create New Feature Specification
+
+## Mental Model
+
+A specification is a contract between the person requesting a feature and the person building it. Writing the spec BEFORE implementation forces you to think through edge cases, acceptance criteria, and scope boundaries while changes are cheap — before any code exists.
+
+Every project uses `.specs/` as the specification directory. Specs are version-organized, independently loadable, and capped at 200 lines.
+
+---
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Extract the feature name and version from `$ARGUMENTS`:
+- **Feature name**: kebab-case identifier (e.g., `session-history`, `auth-flow`)
+- **Version**: semver string (e.g., `v0.3.0`)
+
+If arguments are missing, ask the user for:
+1. Feature name (what is being built)
+2. Target version (which release this belongs to)
+
+### Step 2: Determine File Path
+
+- **Multi-feature version** (directory already exists or multiple features planned):
+  `.specs/{version}/{feature-name}.md`
+- **Single-feature version** (one spec covers the whole version):
+  `.specs/{version}.md`
+
+If `.specs/` does not exist at the project root, create it.
+
+If `.specs/{version}/` does not exist and you're using the directory form, create it.
+
+### Step 3: Create the Spec File
+
+Write the file using the standard template from `references/template.md`.
+
+Pre-fill:
+- **Version**: from arguments
+- **Status**: `planned`
+- **Last Updated**: today's date (YYYY-MM-DD)
+- **Feature name**: from arguments
+
+Leave all other sections as placeholders for the user to fill.
+
+### Step 4: Guide Content Creation
+
+After creating the file, guide the user through filling it out:
+
+1. **Intent** — What problem does this solve? Who has this problem? (2-3 sentences)
+2. **Acceptance Criteria** — Use the `specification-writing` skill for EARS format and Given/When/Then patterns
+3. **Key Files** — Glob the codebase to identify existing files relevant to this feature
+4. **Schema / Data Model** — Reference file paths only, never inline schemas
+5. **API Endpoints** — Table format: Method | Path | Description
+6. **Requirements** — EARS format, numbered FR-1, FR-2, NFR-1, etc.
+7. **Dependencies** — What this feature depends on
+8. **Out of Scope** — Explicit non-goals to prevent scope creep
+
+### Step 5: Validate
+
+Before finishing:
+- [ ] File is ≤200 lines
+- [ ] No source code, SQL, or type definitions reproduced inline
+- [ ] Status is `planned`
+- [ ] All required sections present (even if some are "N/A" or "TBD")
+- [ ] Acceptance criteria are testable
+
+---
+
+## Hard Constraints
+
+- **≤200 lines per spec.** If a feature needs more, split into sub-specs with a parent `_overview.md` (≤50 lines) linking them.
+- **Reference, don't reproduce.** Write `see src/engine/db/migrations/002.sql lines 48-70` — never paste the SQL.
+- **Independently loadable.** Each spec file must be useful without loading any other file.
+- **EARS format for requirements.** Use the `specification-writing` skill for templates and examples.
+
+---
+
+## Ambiguity Policy
+
+- If the user doesn't specify a version, ask — do not assume.
+- If the feature scope is unclear, write a minimal spec with `## Open Questions` listing what needs clarification.
+- If a spec already exists for this feature, inform the user and suggest `/spec-update` instead.
+
+---
+
+## Reference Files
+
+| File | Contents |
+|------|----------|
+| `references/template.md` | Full standard template with field descriptions and examples |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/references/template.md

@@ -0,0 +1,110 @@
+# Specification Template
+
+Standard template for all feature specifications. Copy this structure when creating a new spec.
+
+---
+
+## Template
+
+```markdown
+# Feature: [Name]
+
+**Version:** v0.X.0
+**Status:** planned
+**Last Updated:** YYYY-MM-DD
+
+## Intent
+
+[What problem does this solve? Who has this problem? What's the cost of not solving it? 2-3 sentences.]
+
+## Acceptance Criteria
+
+[Testable criteria. Use Given/When/Then for complex flows, checklists for simple features, or tables for business rules. Every criterion must be verifiable.]
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+## Key Files
+
+[File paths most relevant to implementation — paths an implementer should read first.]
+
+**Backend:**
+- `src/path/to/file.py` — [brief description]
+
+**Frontend:**
+- `src/web/path/to/component.svelte` — [brief description]
+
+**Tests:**
+- `tests/path/to/test_file.py` — [brief description]
+
+## Schema / Data Model
+
+[Reference migration files and model files by path. Describe what changes — do NOT paste DDL, Pydantic models, or TypeScript interfaces.]
+
+- New table: `table_name` — see `src/db/migrations/NNN.sql`
+- Modified: `existing_table` — added `column_name` column
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/resource` | List resources with pagination |
+| POST | `/api/resource` | Create a new resource |
+
+## Requirements
+
+### Functional Requirements
+
+- FR-1: [EARS format requirement — see specification-writing skill for templates]
+- FR-2: When [event], the system shall [action].
+- FR-3: If [unwanted condition], then the system shall [action].
+
+### Non-Functional Requirements
+
+- NFR-1: The system shall respond to [endpoint] within [N]ms at the [percentile] percentile.
+- NFR-2: [Security, accessibility, scalability requirement]
+
+## Dependencies
+
+- [External system, library, or feature this depends on]
+- [Blocked by: feature X must ship first]
+
+## Out of Scope
+
+- [Explicit non-goal 1 — prevents scope creep]
+- [Explicit non-goal 2]
+
+## Implementation Notes
+
+[Post-implementation only. Leave empty in planned specs. After building, document what actually shipped vs. what was planned.]
+
+## Discrepancies
+
+[Post-implementation only. Document gaps between spec intent and actual build. Prevents next session from re-planning decided work.]
+```
+
+---
+
+## Field Descriptions
+
+| Section | Required | When to Fill |
+|---------|----------|-------------|
+| Intent | Always | At creation |
+| Acceptance Criteria | Always | At creation |
+| Key Files | Always | At creation (update post-implementation) |
+| Schema / Data Model | If applicable | At creation |
+| API Endpoints | If applicable | At creation |
+| Requirements | Always | At creation |
+| Dependencies | If applicable | At creation |
+| Out of Scope | Always | At creation |
+| Implementation Notes | Post-implementation | After building |
+| Discrepancies | Post-implementation | After building |
+
+## Status Values
+
+| Status | Meaning |
+|--------|---------|
+| `planned` | Spec written, implementation not started |
+| `partial` | Some acceptance criteria implemented, work ongoing |
+| `implemented` | All acceptance criteria met, as-built notes complete |

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

@@ -0,0 +1,124 @@
+---
+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
+---
+
+# As-Built Spec Update
+
+## Mental Model
+
+Specs that say "planned" after code ships cause the next AI session to re-plan already-done work. The as-built update is the final step of every implementation — it closes the loop between what was planned and what was built.
+
+This is not optional. Every implementation ends with a spec update.
+
+---
+
+## The 6-Step Workflow
+
+### Step 1: Find the Spec
+
+```
+Glob: .specs/**/*.md
+```
+
+Search for the feature name in spec file names and content. If the user provides a spec path or feature name as `$ARGUMENTS`, use that directly.
+
+If no spec exists:
+- For substantial changes: create one using `/spec-new`
+- For trivial changes (bug fixes, config): note "spec not needed" and stop
+
+### Step 2: Set Status
+
+Update the `**Status:**` field:
+- `implemented` — all acceptance criteria are met
+- `partial` — some criteria met, work ongoing or deferred
+
+Never leave status as `planned` after implementation work has been done.
+
+### Step 3: Check Off Acceptance Criteria
+
+Review each acceptance criterion in the spec:
+- Mark as `[x]` if the criterion is met and verified (tests pass, behavior confirmed)
+- Leave as `[ ]` if not yet implemented
+- Add a note next to deferred criteria explaining why
+
+If criteria were met through different means than originally planned, note the deviation.
+
+### Step 4: Add Implementation Notes
+
+In the `## Implementation Notes` section, document:
+- **Deviations from the original spec** — what changed and why
+- **Key design decisions made during implementation** — choices that weren't in the spec
+- **Surprising findings** — edge cases discovered, performance characteristics, limitations
+- **Trade-offs accepted** — what was sacrificed and why
+
+Keep notes concise. Reference file paths, not code.
+
+### Step 5: Update File Paths
+
+In the `## Key Files` section:
+- Add files that were created during implementation
+- Remove files that no longer exist
+- Update paths that moved
+
+Verify paths exist before listing them. Use absolute project-relative paths.
+
+### Step 6: Update Metadata
+
+- Set `**Last Updated:**` to today's date (YYYY-MM-DD)
+- Verify `**Version:**` is correct
+
+---
+
+## Handling Edge Cases
+
+### Spec Already "Implemented"
+
+If the spec is already marked `implemented` and new changes affect the feature:
+1. Check if acceptance criteria still hold
+2. Update Implementation Notes with the new changes
+3. Add any new Discrepancies between spec and current code
+4. Update Last Updated date
+
+### No Spec Exists
+
+If there is no spec for the feature:
+1. Ask: is this a substantial feature or a minor fix?
+2. For substantial features: create one with `/spec-new`, then update it
+3. For minor fixes: no spec needed — report this and stop
+
+### Spec Has Unresolved Discrepancies
+
+If the `## Discrepancies` section has open items:
+1. Check if the current implementation resolves any of them
+2. Remove resolved discrepancies
+3. Add any new discrepancies discovered
+
+---
+
+## Validation Checklist
+
+Before finishing the update:
+- [ ] Status reflects the actual implementation state
+- [ ] All implemented acceptance criteria are checked off
+- [ ] Implementation Notes document deviations from original spec
+- [ ] File paths in Key Files are accurate and verified
+- [ ] Last Updated date is today
+- [ ] Spec is still ≤200 lines
+- [ ] No source code was pasted inline (references only)
+
+---
+
+## Ambiguity Policy
+
+- If unclear which spec to update, list all candidates and ask the user.
+- If the implementation deviated significantly from the spec, document it
+  honestly in Implementation Notes — do not retroactively change the original
+  requirements to match what was built.
+- If acceptance criteria are ambiguous about whether they're met, note the
+  ambiguity in Discrepancies rather than checking them off optimistically.