codeforge-dev 1.8.0 → 1.10.0

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

@@ -0,0 +1,142 @@
+---
+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.
+
+---
+
+## Approval Gate
+
+Before performing an as-built update, check the spec's `**Approval:**` status:
+- If `user-approved` → proceed with the update
+- If `draft` → warn the user: "This spec is still `draft`. It should have gone through `/spec-refine` before implementation. Run `/spec-refine` now to validate, or proceed with the as-built update if the user confirms."
+
+This is a warning, not a blocker — the user decides whether to refine first or update as-is.
+
+---
+
+## 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
+- Preserve the `**Approval:**` status — do NOT downgrade `user-approved` to `draft`
+- If the as-built update introduces new decisions not in the original spec, add them to `## Resolved Questions` if the user confirmed them, or `## Open Questions` if they were assumed during implementation
+
+---
+
+## 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
+- [ ] `**Approval:**` status is preserved (not downgraded)
+- [ ] New implementation decisions are tracked in Resolved Questions or Open Questions
+- [ ] If the spec has grown past ~200 lines, note it and suggest splitting in a future pass
+- [ ] If `**Approval:**` is still `draft`, user was warned and confirmed proceeding
+- [ ] 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.
+- A spec-reminder advisory hook fires at Stop when code was modified but
+  specs weren't updated. If you see "[Spec Reminder]" in context, that's
+  the trigger — use this skill to resolve it.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/specification-writing/SKILL.md

@@ -30,11 +30,11 @@ Write specifications with a hostile reader in mind -- someone who will interpret
 
 ---
 
-## Spec Sizing & AI Context Rules
+## Spec Sizing Guidelines
 
 Specifications are loaded into AI context windows with limited capacity. Design for consumption.
 
-**Hard limit:** ≤200 lines per spec file. If a feature needs more, split into sub-specs (one per sub-feature) with a ≤50 line overview linking them.
+**Recommended target:** ~200 lines per spec file. When a spec grows beyond that, consider splitting into sub-specs (one per sub-feature) with a concise overview linking them. Complex features may justify longer specs — completeness matters more than hitting a number.
 
 **Reference, don't reproduce:** Never inline source code, SQL DDL, Pydantic models, or TypeScript interfaces. Reference the file path and line range instead. The code is the source of truth — duplicated snippets go stale silently.
 
@@ -179,9 +179,10 @@ Every spec file starts with metadata:
 **Version:** v0.X.0
 **Status:** implemented | partial | planned
 **Last Updated:** YYYY-MM-DD
+**Approval:** draft | user-approved
 ```
 
-Status tells you whether to trust it, version tells you where it belongs, last-updated tells you when it was last verified.
+Status tells you whether to trust it, version tells you where it belongs, last-updated tells you when it was last verified. Approval tells you whether decisions in the spec have been explicitly validated by the user (`user-approved`) or are AI-generated hypotheses (`draft`).
 
 ### 1. Problem Statement
 What problem does this feature solve? Who has this problem? What's the cost of not solving it? (2-3 sentences)
@@ -218,20 +219,22 @@ so that [I can detect suspicious reset patterns].
 Use EARS format. Number each requirement for traceability:
 
 ```markdown
-- FR-1: When a user requests a password reset, the system shall send a reset email
+- FR-1 [assumed]: When a user requests a password reset, the system shall send a reset email
   to the registered email address within 60 seconds.
-- FR-2: The reset link shall contain a cryptographically random token (min 32 bytes).
-- FR-3: If the reset token is expired or already used, then the system shall display
+- FR-2 [assumed]: The reset link shall contain a cryptographically random token (min 32 bytes).
+- FR-3 [assumed]: If the reset token is expired or already used, then the system shall display
   an error message and offer to send a new reset email.
+
+Tag each requirement `[assumed]` when first written. Requirements become `[user-approved]` only after explicit user validation via `/spec-refine`.
 ```
 
 ### 5. Non-Functional Requirements
 Performance, security, scalability, accessibility:
 
 ```markdown
-- NFR-1: The password reset endpoint shall respond within 200ms (p95).
-- NFR-2: Reset tokens shall be stored as bcrypt hashes, not plaintext.
-- NFR-3: The reset flow shall be accessible with screen readers (WCAG 2.1 AA).
+- NFR-1 [assumed]: The password reset endpoint shall respond within 200ms (p95).
+- NFR-2 [assumed]: Reset tokens shall be stored as bcrypt hashes, not plaintext.
+- NFR-3 [assumed]: The reset flow shall be accessible with screen readers (WCAG 2.1 AA).
 ```
 
 ### 6. Edge Cases
@@ -249,13 +252,16 @@ The cases nobody thinks about until they happen:
 ### 7. Out of Scope
 Explicit non-goals to prevent scope creep (can reference the Scope section or expand here).
 
-### 8. Key Files
+### 8. Resolved Questions
+Decisions explicitly approved by the user via `/spec-refine`. Each entry: decision topic, chosen option, options considered, date, brief rationale. This section starts empty and is populated during the refinement process.
+
+### 9. Key Files
 Source files most relevant to this feature — paths an implementer should read.
 
-### 9. Implementation Notes
+### 10. Implementation Notes
 Post-implementation only. Capture deviations from the original spec — what changed and why.
 
-### 10. Discrepancies
+### 11. Discrepancies
 Gaps between spec intent and actual build. Prevents the next session from re-planning decided work.
 
 ---
@@ -309,6 +315,7 @@ These defaults apply when the user does not specify a preference. State the assu
 - **Edge cases:** Always include at least: empty input, maximum input, concurrent access, and external service failure.
 - **Out of scope:** Always include an out-of-scope section, even if brief, to establish boundaries.
 - **Numbering:** Number all requirements (FR-1, NFR-1) for traceability in code reviews and tests.
+- **Approval markers:** All requirements start as `[assumed]`. Only `/spec-refine` with explicit user validation upgrades them to `[user-approved]`. Spec-level `**Approval:**` starts as `draft` and becomes `user-approved` only when all requirements are `[user-approved]`.
 
 ---
 

package/.devcontainer/scripts/check-setup.sh

@@ -5,34 +5,37 @@
 echo "CodeForge Setup Check"
 echo "━━━━━━━━━━━━━━━━━━━━"
 
-PASS=0; FAIL=0; WARN=0
+PASS=0
+FAIL=0
+WARN=0
 
 check() {
-    local label="$1" cmd="$2"
-    if eval "$cmd" >/dev/null 2>&1; then
-        printf "  ✓ %s\n" "$label"
-        PASS=$((PASS + 1))
-    else
-        printf "  ✗ %s\n" "$label"
-        FAIL=$((FAIL + 1))
-    fi
+	local label="$1" cmd="$2"
+	if eval "$cmd" >/dev/null 2>&1; then
+		printf "  ✓ %s\n" "$label"
+		PASS=$((PASS + 1))
+	else
+		printf "  ✗ %s\n" "$label"
+		FAIL=$((FAIL + 1))
+	fi
 }
 
 warn_check() {
-    local label="$1" cmd="$2"
-    if eval "$cmd" >/dev/null 2>&1; then
-        printf "  ✓ %s\n" "$label"
-        PASS=$((PASS + 1))
-    else
-        printf "  ⚠ %s\n" "$label"
-        WARN=$((WARN + 1))
-    fi
+	local label="$1" cmd="$2"
+	if eval "$cmd" >/dev/null 2>&1; then
+		printf "  ✓ %s\n" "$label"
+		PASS=$((PASS + 1))
+	else
+		printf "  ⚠ %s\n" "$label"
+		WARN=$((WARN + 1))
+	fi
 }
 
 echo ""
 echo "Core:"
 check "Claude Code installed" "command -v claude"
-check "cc alias available" "type cc"
+warn_check "Claude native binary" "[ -x /usr/local/bin/claude ]"
+check "cc alias configured" "grep -q 'alias cc=' ~/.bashrc 2>/dev/null || grep -q 'alias cc=' ~/.zshrc 2>/dev/null"
 check "Config directory exists" "[ -d '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}' ]"
 check "Settings file exists" "[ -f '${CLAUDE_CONFIG_DIR:-/workspaces/.claude}/settings.json' ]"
 
@@ -54,10 +57,6 @@ echo ""
 echo "Development:"
 warn_check "biome" "command -v biome"
 warn_check "ruff" "command -v ruff"
-warn_check "dprint" "command -v dprint"
-warn_check "shfmt" "command -v shfmt"
-warn_check "shellcheck" "command -v shellcheck"
-warn_check "hadolint" "command -v hadolint"
 warn_check "ast-grep" "command -v ast-grep"
 warn_check "tmux" "command -v tmux"
 
@@ -66,7 +65,7 @@ echo "━━━━━━━━━━━━━━━━━━━━"
 echo "  $PASS passed, $FAIL failed, $WARN warnings"
 
 if [ $FAIL -gt 0 ]; then
-    echo ""
-    echo "  Run 'cc-tools' for detailed version info."
-    exit 1
+	echo ""
+	echo "  Run 'cc-tools' for detailed version info."
+	exit 1
 fi

package/.devcontainer/scripts/setup-aliases.sh

@@ -6,82 +6,94 @@ CLAUDE_DIR="${CLAUDE_CONFIG_DIR:?CLAUDE_CONFIG_DIR not set}"
 echo "[setup-aliases] Configuring Claude aliases..."
 
 # Simple alias definitions (not functions — functions don't behave reliably across shell contexts)
-ALIAS_CC='alias cc='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command claude --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
-ALIAS_CLAUDE='alias claude='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command claude --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
-ALIAS_CCRAW='alias ccraw="command claude"'
+# Aliases reference $_CLAUDE_BIN which is resolved at shell startup to prefer the native binary.
+ALIAS_CC='alias cc='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command "$_CLAUDE_BIN" --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
+ALIAS_CLAUDE='alias claude='"'"'CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 command "$_CLAUDE_BIN" --system-prompt-file "$CLAUDE_CONFIG_DIR/system-prompt.md" --permission-mode plan --allow-dangerously-skip-permissions'"'"''
+ALIAS_CCRAW='alias ccraw='"'"'command "$_CLAUDE_BIN"'"'"''
 
 for rc in ~/.bashrc ~/.zshrc; do
-    if [ -f "$rc" ]; then
-        # --- Backup before modifying ---
-        cp "$rc" "${rc}.bak.$(date +%s)" 2>/dev/null || true
-        # Clean old backups (keep last 3)
-        ls -t "${rc}.bak."* 2>/dev/null | tail -n +4 | xargs rm -f 2>/dev/null || true
+	if [ -f "$rc" ]; then
+		# --- Backup before modifying ---
+		cp "$rc" "${rc}.bak.$(date +%s)" 2>/dev/null || true
+		# Clean old backups (keep last 3)
+		ls -t "${rc}.bak."* 2>/dev/null | tail -n +4 | xargs rm -f 2>/dev/null || true
 
-        # --- Cleanup old definitions ---
+		# --- Cleanup old definitions ---
 
-        # Remove old cc alias
-        if grep -q "alias cc=" "$rc" 2>/dev/null; then
-            sed -i '/alias cc=/d' "$rc"
-            echo "[setup-aliases] Removed old cc alias from $(basename $rc)"
-        fi
-        # Remove old cc function (single-line or multi-line)
-        if grep -q "^cc()" "$rc" 2>/dev/null; then
-            sed -i '/^cc() {/,/^}/d' "$rc"
-            echo "[setup-aliases] Removed old cc function from $(basename $rc)"
-        fi
-        # Remove old _claude_with_config function
-        if grep -q "^_claude_with_config()" "$rc" 2>/dev/null; then
-            sed -i '/^_claude_with_config() {/,/^}/d' "$rc"
-            echo "[setup-aliases] Removed old _claude_with_config function from $(basename $rc)"
-        fi
-        # Remove old claude function override
-        if grep -q "^claude() {" "$rc" 2>/dev/null; then
-            sed -i '/^claude() { _claude_with_config/d' "$rc"
-            echo "[setup-aliases] Removed old claude function from $(basename $rc)"
-        fi
-        # Remove old claude alias
-        if grep -q "alias claude=" "$rc" 2>/dev/null; then
-            sed -i '/alias claude=/d' "$rc"
-        fi
-        # Remove old ccraw alias
-        if grep -q "alias ccraw=" "$rc" 2>/dev/null; then
-            sed -i '/alias ccraw=/d' "$rc"
-        fi
-        # Remove old specwright alias
-        if grep -q "alias specwright=" "$rc" 2>/dev/null; then
-            sed -i '/alias specwright=/d' "$rc"
-        fi
-        # Remove old cc-tools/check-setup functions
-        if grep -q "^cc-tools()" "$rc" 2>/dev/null; then
-            sed -i '/^cc-tools() {/,/^}/d' "$rc"
-        fi
-        if grep -q "alias check-setup=" "$rc" 2>/dev/null; then
-            sed -i '/alias check-setup=/d' "$rc"
-        fi
+		# Remove old cc alias
+		if grep -q "alias cc=" "$rc" 2>/dev/null; then
+			sed -i '/alias cc=/d' "$rc"
+			echo "[setup-aliases] Removed old cc alias from $(basename $rc)"
+		fi
+		# Remove old cc function (single-line or multi-line)
+		if grep -q "^cc()" "$rc" 2>/dev/null; then
+			sed -i '/^cc() {/,/^}/d' "$rc"
+			echo "[setup-aliases] Removed old cc function from $(basename $rc)"
+		fi
+		# Remove old _claude_with_config function
+		if grep -q "^_claude_with_config()" "$rc" 2>/dev/null; then
+			sed -i '/^_claude_with_config() {/,/^}/d' "$rc"
+			echo "[setup-aliases] Removed old _claude_with_config function from $(basename $rc)"
+		fi
+		# Remove old claude function override
+		if grep -q "^claude() {" "$rc" 2>/dev/null; then
+			sed -i '/^claude() { _claude_with_config/d' "$rc"
+			echo "[setup-aliases] Removed old claude function from $(basename $rc)"
+		fi
+		# Remove old claude alias
+		if grep -q "alias claude=" "$rc" 2>/dev/null; then
+			sed -i '/alias claude=/d' "$rc"
+		fi
+		# Remove old ccraw alias
+		if grep -q "alias ccraw=" "$rc" 2>/dev/null; then
+			sed -i '/alias ccraw=/d' "$rc"
+		fi
+		# Remove old specwright alias
+		if grep -q "alias specwright=" "$rc" 2>/dev/null; then
+			sed -i '/alias specwright=/d' "$rc"
+		fi
+		# Remove old cc-tools/check-setup functions
+		if grep -q "^cc-tools()" "$rc" 2>/dev/null; then
+			sed -i '/^cc-tools() {/,/^}/d' "$rc"
+		fi
+		if grep -q "alias check-setup=" "$rc" 2>/dev/null; then
+			sed -i '/alias check-setup=/d' "$rc"
+		fi
+		# --- Add environment and aliases (idempotent) ---
+		# Guard: skip if aliases already present from a previous run
+		if grep -q '# Claude Code environment and aliases' "$rc" 2>/dev/null; then
+			echo "[setup-aliases] Aliases already present in $(basename $rc), skipping"
+			continue
+		fi
+		echo "" >>"$rc"
+		echo "# Claude Code environment and aliases (managed by setup-aliases.sh)" >>"$rc"
+		# Export CLAUDE_CONFIG_DIR so it's available in all shells (not just VS Code remoteEnv)
+		if ! grep -q 'export CLAUDE_CONFIG_DIR=' "$rc" 2>/dev/null; then
+			echo "export CLAUDE_CONFIG_DIR=\"${CLAUDE_CONFIG_DIR}\"" >>"$rc"
+		fi
+		# Export UTF-8 locale so tmux renders Unicode correctly (docker exec doesn't inherit locale)
+		if ! grep -q 'export LANG=en_US.UTF-8' "$rc" 2>/dev/null; then
+			echo 'export LANG=en_US.UTF-8' >>"$rc"
+			echo 'export LC_ALL=en_US.UTF-8' >>"$rc"
+		fi
+		# Prefer native binary over npm-installed version
+		# 'claude install' puts the binary at ~/.local/bin/claude
+		# Legacy manual installs used /usr/local/bin/claude — check both
+		cat >>"$rc" <<'CLAUDEBIN_EOF'
+if [ -x "$HOME/.local/bin/claude" ]; then
+    _CLAUDE_BIN="$HOME/.local/bin/claude"
+elif [ -x /usr/local/bin/claude ]; then
+    _CLAUDE_BIN=/usr/local/bin/claude
+else
+    _CLAUDE_BIN=claude
+fi
+CLAUDEBIN_EOF
+		echo "$ALIAS_CC" >>"$rc"
+		echo "$ALIAS_CLAUDE" >>"$rc"
+		echo "$ALIAS_CCRAW" >>"$rc"
 
-        # --- Add environment and aliases (idempotent) ---
-        # Guard: skip if aliases already present from a previous run
-        if grep -q '# Claude Code environment and aliases' "$rc" 2>/dev/null; then
-            echo "[setup-aliases] Aliases already present in $(basename $rc), skipping"
-            continue
-        fi
-        echo "" >> "$rc"
-        echo "# Claude Code environment and aliases (managed by setup-aliases.sh)" >> "$rc"
-        # Export CLAUDE_CONFIG_DIR so it's available in all shells (not just VS Code remoteEnv)
-        if ! grep -q 'export CLAUDE_CONFIG_DIR=' "$rc" 2>/dev/null; then
-            echo "export CLAUDE_CONFIG_DIR=\"${CLAUDE_CONFIG_DIR}\"" >> "$rc"
-        fi
-        # Export UTF-8 locale so tmux renders Unicode correctly (docker exec doesn't inherit locale)
-        if ! grep -q 'export LANG=en_US.UTF-8' "$rc" 2>/dev/null; then
-            echo 'export LANG=en_US.UTF-8' >> "$rc"
-            echo 'export LC_ALL=en_US.UTF-8' >> "$rc"
-        fi
-        echo "$ALIAS_CC" >> "$rc"
-        echo "$ALIAS_CLAUDE" >> "$rc"
-        echo "$ALIAS_CCRAW" >> "$rc"
-
-        # cc-tools: list all available CodeForge tools with version info
-        cat >> "$rc" << 'CCTOOLS_EOF'
+		# cc-tools: list all available CodeForge tools with version info
+		cat >>"$rc" <<'CCTOOLS_EOF'
 cc-tools() {
   echo "CodeForge Available Tools"
   echo "━━━━━━━━━━━━━━━━━━━━━━━━"
@@ -101,12 +113,12 @@ cc-tools() {
 }
 CCTOOLS_EOF
 
-        # check-setup: alias to the health check script
-        DEVCONTAINER_SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-        echo "alias check-setup='bash ${DEVCONTAINER_SCRIPTS}/check-setup.sh'" >> "$rc"
+		# check-setup: alias to the health check script
+		DEVCONTAINER_SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+		echo "alias check-setup='bash ${DEVCONTAINER_SCRIPTS}/check-setup.sh'" >>"$rc"
 
-        echo "[setup-aliases] Added aliases to $(basename $rc)"
-    fi
+		echo "[setup-aliases] Added aliases to $(basename $rc)"
+	fi
 done
 
 echo "[setup-aliases] Aliases configured:"