codeforge-dev 1.5.7 → 1.7.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/specification-writing/references/ears-templates.md

@@ -0,0 +1,239 @@
+# EARS Requirement Templates
+
+Templates and filled examples for each EARS (Easy Approach to Requirements Syntax) pattern type.
+
+## Contents
+
+- [Ubiquitous Requirements](#ubiquitous-requirements)
+- [Event-Driven Requirements](#event-driven-requirements)
+- [State-Driven Requirements](#state-driven-requirements)
+- [Unwanted Behavior Requirements](#unwanted-behavior-requirements)
+- [Optional Feature Requirements](#optional-feature-requirements)
+- [Compound Requirements](#compound-requirements)
+- [Writing Tips](#writing-tips)
+
+---
+
+## Ubiquitous Requirements
+
+**Template:**
+```
+The <system> shall <action>.
+```
+
+Requirements that are always active, with no trigger condition. These define invariant behaviors.
+
+### Examples
+
+```
+The API shall return responses in JSON format with UTF-8 encoding.
+
+The system shall log all authentication events with timestamp, user ID, and outcome.
+
+The application shall enforce HTTPS for all client-server communication.
+
+The database shall store timestamps in UTC.
+
+The API shall include a request-id header in every response.
+```
+
+### Anti-patterns
+
+```
+❌ The system should be fast.
+   → Not testable. How fast? Measured how?
+
+❌ The system shall be user-friendly.
+   → Not testable. Define specific interaction requirements.
+
+✅ The API shall respond to health check requests within 50ms (p99).
+✅ The login form shall support keyboard navigation (tab order: email → password → submit).
+```
+
+---
+
+## Event-Driven Requirements
+
+**Template:**
+```
+When <event>, the <system> shall <action>.
+```
+
+Requirements triggered by a specific, detectable event. The event is the precondition.
+
+### Examples
+
+```
+When a user submits a registration form, the system shall validate all fields
+and return validation errors within 200ms.
+
+When a payment transaction fails, the system shall:
+  1. Log the failure with transaction ID, error code, and timestamp.
+  2. Send a failure notification to the user within 60 seconds.
+  3. Release the reserved inventory.
+
+When a file upload exceeds 50MB, the system shall reject the upload with
+HTTP 413 and a message indicating the maximum file size.
+
+When a user's session has been inactive for 30 minutes, the system shall
+invalidate the session and redirect to the login page.
+
+When the system receives a webhook event with an unrecognized event type,
+the system shall log the event payload and return HTTP 200 (acknowledge but ignore).
+```
+
+### Anti-patterns
+
+```
+❌ When the user does something wrong, show an error.
+   → What action? What error? How displayed?
+
+✅ When the user submits a form with an invalid email format,
+   the system shall display an inline error message below the email field
+   stating "Please enter a valid email address".
+```
+
+---
+
+## State-Driven Requirements
+
+**Template:**
+```
+While <state>, the <system> shall <action>.
+```
+
+Requirements that apply continuously while the system is in a specific state.
+
+### Examples
+
+```
+While the system is in maintenance mode, the API shall return HTTP 503
+with a "Retry-After" header for all endpoints except /health.
+
+While a user account is locked, the system shall reject all login attempts
+and display a message with the unlock time.
+
+While the message queue depth exceeds 10,000 messages, the system shall
+activate the secondary consumer group.
+
+While the database is performing a backup, the system shall serve read
+requests from the read replica and queue write requests.
+
+While the system is operating in degraded mode, the dashboard shall display
+a banner indicating limited functionality and estimated recovery time.
+```
+
+---
+
+## Unwanted Behavior Requirements
+
+**Template:**
+```
+If <unwanted condition>, then the <system> shall <action>.
+```
+
+Requirements for handling errors, failures, and edge cases. These cover what happens when things go wrong.
+
+### Examples
+
+```
+If the external payment gateway does not respond within 5 seconds,
+then the system shall retry once after 2 seconds, and if the retry
+also fails, return a "payment processing delayed" message to the user.
+
+If the database connection pool is exhausted, then the system shall
+queue incoming requests for up to 30 seconds before returning HTTP 503.
+
+If a user attempts to access a resource they do not own, then the system
+shall return HTTP 403, log the access attempt with the user ID and resource ID,
+and increment the security audit counter.
+
+If the uploaded file contains an unsupported MIME type, then the system shall
+reject the file with a message listing the supported types.
+
+If the disk usage exceeds 90%, then the system shall send an alert to the
+operations team and begin purging temporary files older than 24 hours.
+```
+
+---
+
+## Optional Feature Requirements
+
+**Template:**
+```
+Where <feature is enabled>, the <system> shall <action>.
+```
+
+Requirements that depend on a configurable feature flag or setting.
+
+### Examples
+
+```
+Where two-factor authentication is enabled, the system shall require
+a TOTP code after successful password verification.
+
+Where the audit log feature is enabled, the system shall record all
+CRUD operations with the actor, action, resource, and timestamp.
+
+Where dark mode is enabled, the system shall render all pages using
+the dark color palette defined in the theme configuration.
+
+Where rate limiting is configured, the system shall enforce the configured
+request limit per API key per minute and return HTTP 429 when exceeded.
+
+Where email notifications are enabled for a user, the system shall send
+a daily digest of unread notifications at the user's configured time.
+```
+
+---
+
+## Compound Requirements
+
+Complex requirements often combine multiple EARS patterns:
+
+### Event + Unwanted Behavior
+
+```
+When a user submits a password reset request:
+  - The system shall send a reset email within 60 seconds.
+  - If the email address is not associated with an account, then the system
+    shall still return a success message (to prevent email enumeration).
+  - If the email service is unavailable, then the system shall queue the
+    email for retry and inform the user that the email may be delayed.
+```
+
+### State + Event
+
+```
+While the system is in read-only mode:
+  - When a user attempts a write operation, the system shall return HTTP 503
+    with a message indicating when write access will be restored.
+  - When an admin issues a "restore write access" command, the system shall
+    exit read-only mode and process any queued write operations in order.
+```
+
+### Requirement Hierarchies
+
+For complex features, use parent-child numbering:
+
+```
+FR-1: User Registration
+  FR-1.1: When a user submits the registration form, the system shall
+          create an account and send a verification email.
+  FR-1.2: If the email is already registered, then the system shall
+          display "An account with this email already exists".
+  FR-1.3: The system shall require passwords of at least 12 characters
+          with at least one uppercase letter and one digit.
+  FR-1.4: Where CAPTCHA is enabled, the registration form shall include
+          a CAPTCHA challenge before submission.
+```
+
+---
+
+## Writing Tips
+
+1. **One requirement per statement.** Don't combine multiple behaviors in one sentence.
+2. **Use "shall" for requirements, "should" for recommendations, "may" for optional.** This is standard requirement language (RFC 2119).
+3. **Be specific about quantities.** Not "quickly" but "within 200ms". Not "many" but "up to 1000".
+4. **Name the actor.** "The system shall..." or "The user shall..." -- never the passive "It should be done".
+5. **State the observable behavior.** Requirements describe what the system does, not how it does it internally.

package/.devcontainer/plugins/devs-marketplace/plugins/protected-files-guard/scripts/guard-protected.py

@@ -14,47 +14,50 @@ import sys
 # Patterns that should be protected from modification
 PROTECTED_PATTERNS = [
     # Environment secrets
-    (r'(^|/)\.env$', "Blocked: .env contains secrets - edit manually if needed"),
-    (r'(^|/)\.env\.[^/]+$', "Blocked: .env.* files contain secrets - edit manually if needed"),
-
+    (r"(^|/)\.env$", "Blocked: .env contains secrets - edit manually if needed"),
+    (
+        r"(^|/)\.env\.[^/]+$",
+        "Blocked: .env.* files contain secrets - edit manually if needed",
+    ),
     # Git internals
-    (r'(^|/)\.git/', "Blocked: .git/ directory is managed by git"),
-
+    (r"(^|/)\.git/", "Blocked: .git/ directory is managed by git"),
     # Lock files (should be modified via package manager)
-    (r'(^|/)package-lock\.json$', "Blocked: package-lock.json - use npm install instead"),
-    (r'(^|/)yarn\.lock$', "Blocked: yarn.lock - use yarn install instead"),
-    (r'(^|/)pnpm-lock\.yaml$', "Blocked: pnpm-lock.yaml - use pnpm install instead"),
-    (r'(^|/)Gemfile\.lock$', "Blocked: Gemfile.lock - use bundle install instead"),
-    (r'(^|/)poetry\.lock$', "Blocked: poetry.lock - use poetry install instead"),
-    (r'(^|/)Cargo\.lock$', "Blocked: Cargo.lock - use cargo build instead"),
-    (r'(^|/)composer\.lock$', "Blocked: composer.lock - use composer install instead"),
-    (r'(^|/)uv\.lock$', "Blocked: uv.lock - use uv sync instead"),
-
+    (
+        r"(^|/)package-lock\.json$",
+        "Blocked: package-lock.json - use npm install instead",
+    ),
+    (r"(^|/)yarn\.lock$", "Blocked: yarn.lock - use yarn install instead"),
+    (r"(^|/)pnpm-lock\.yaml$", "Blocked: pnpm-lock.yaml - use pnpm install instead"),
+    (r"(^|/)Gemfile\.lock$", "Blocked: Gemfile.lock - use bundle install instead"),
+    (r"(^|/)poetry\.lock$", "Blocked: poetry.lock - use poetry install instead"),
+    (r"(^|/)Cargo\.lock$", "Blocked: Cargo.lock - use cargo build instead"),
+    (r"(^|/)composer\.lock$", "Blocked: composer.lock - use composer install instead"),
+    (r"(^|/)uv\.lock$", "Blocked: uv.lock - use uv sync instead"),
     # Certificates and keys
-    (r'\.pem$', "Blocked: .pem files contain sensitive cryptographic material"),
-    (r'\.key$', "Blocked: .key files contain sensitive cryptographic material"),
-    (r'\.crt$', "Blocked: .crt certificate files should not be edited directly"),
-    (r'\.p12$', "Blocked: .p12 files contain sensitive cryptographic material"),
-    (r'\.pfx$', "Blocked: .pfx files contain sensitive cryptographic material"),
-
+    (r"\.pem$", "Blocked: .pem files contain sensitive cryptographic material"),
+    (r"\.key$", "Blocked: .key files contain sensitive cryptographic material"),
+    (r"\.crt$", "Blocked: .crt certificate files should not be edited directly"),
+    (r"\.p12$", "Blocked: .p12 files contain sensitive cryptographic material"),
+    (r"\.pfx$", "Blocked: .pfx files contain sensitive cryptographic material"),
     # Credential files
-    (r'(^|/)credentials\.json$', "Blocked: credentials.json contains secrets"),
-    (r'(^|/)secrets\.yaml$', "Blocked: secrets.yaml contains secrets"),
-    (r'(^|/)secrets\.yml$', "Blocked: secrets.yml contains secrets"),
-    (r'(^|/)secrets\.json$', "Blocked: secrets.json contains secrets"),
-    (r'(^|/)\.secrets$', "Blocked: .secrets file contains secrets"),
-
+    (r"(^|/)credentials\.json$", "Blocked: credentials.json contains secrets"),
+    (r"(^|/)secrets\.yaml$", "Blocked: secrets.yaml contains secrets"),
+    (r"(^|/)secrets\.yml$", "Blocked: secrets.yml contains secrets"),
+    (r"(^|/)secrets\.json$", "Blocked: secrets.json contains secrets"),
+    (r"(^|/)\.secrets$", "Blocked: .secrets file contains secrets"),
     # Auth directories and files
-    (r'(^|/)\.ssh/', "Blocked: .ssh/ contains sensitive authentication data"),
-    (r'(^|/)\.aws/', "Blocked: .aws/ contains AWS credentials"),
-    (r'(^|/)\.netrc$', "Blocked: .netrc contains authentication credentials"),
-    (r'(^|/)\.npmrc$', "Blocked: .npmrc may contain auth tokens - edit manually if needed"),
-    (r'(^|/)\.pypirc$', "Blocked: .pypirc contains PyPI credentials"),
-
+    (r"(^|/)\.ssh/", "Blocked: .ssh/ contains sensitive authentication data"),
+    (r"(^|/)\.aws/", "Blocked: .aws/ contains AWS credentials"),
+    (r"(^|/)\.netrc$", "Blocked: .netrc contains authentication credentials"),
+    (
+        r"(^|/)\.npmrc$",
+        "Blocked: .npmrc may contain auth tokens - edit manually if needed",
+    ),
+    (r"(^|/)\.pypirc$", "Blocked: .pypirc contains PyPI credentials"),
     # Other sensitive files
-    (r'(^|/)id_rsa', "Blocked: SSH private key file"),
-    (r'(^|/)id_ed25519', "Blocked: SSH private key file"),
-    (r'(^|/)id_ecdsa', "Blocked: SSH private key file"),
+    (r"(^|/|-)id_rsa($|\.)", "Blocked: SSH private key file"),
+    (r"(^|/)id_ed25519", "Blocked: SSH private key file"),
+    (r"(^|/)id_ecdsa", "Blocked: SSH private key file"),
 ]
 
 
@@ -65,7 +68,7 @@ def check_path(file_path: str) -> tuple[bool, str]:
         (is_protected, message)
     """
     # Normalize path for consistent matching
-    normalized = file_path.replace('\\', '/')
+    normalized = file_path.replace("\\", "/")
 
     for pattern, message in PROTECTED_PATTERNS:
         if re.search(pattern, normalized, re.IGNORECASE):
@@ -87,9 +90,7 @@ def main():
 
         if is_protected:
             # Output error message and exit 2 to block
-            print(json.dumps({
-                "error": message
-            }))
+            print(json.dumps({"error": message}))
             sys.exit(2)
 
         # Allow edit to proceed

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

@@ -6,8 +6,8 @@ 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='"'"'command claude --system-prompt-file .claude/system-prompt.md --permission-mode plan --allow-dangerously-skip-permissions'"'"''
-ALIAS_CLAUDE='alias claude='"'"'command claude --system-prompt-file .claude/system-prompt.md --permission-mode plan --allow-dangerously-skip-permissions'"'"''
+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"'
 
 for rc in ~/.bashrc ~/.zshrc; do
@@ -47,7 +47,12 @@ for rc in ~/.bashrc ~/.zshrc; do
             sed -i '/alias specwright=/d' "$rc"
         fi
 
-        # --- Add environment, auto-tmux, and aliases ---
+        # --- 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)
@@ -59,21 +64,6 @@ for rc in ~/.bashrc ~/.zshrc; do
             echo 'export LANG=en_US.UTF-8' >> "$rc"
             echo 'export LC_ALL=en_US.UTF-8' >> "$rc"
         fi
-        # Auto-enter tmux for Agent Teams split-pane support
-        # Guards: not already in tmux, interactive shell only, tmux available
-        if ! grep -q 'Auto-enter tmux' "$rc" 2>/dev/null; then
-            cat >> "$rc" << 'TMUX_BLOCK'
-
-# Auto-enter tmux for Agent Teams split-pane support
-if [ -z "$TMUX" ] && [ -n "$PS1" ] && command -v tmux &>/dev/null; then
-    if tmux has-session -t claude-teams 2>/dev/null; then
-        exec tmux -u new-session -t claude-teams
-    else
-        exec tmux -u new-session -s claude-teams
-    fi
-fi
-TMUX_BLOCK
-        fi
         echo "$ALIAS_CC" >> "$rc"
         echo "$ALIAS_CLAUDE" >> "$rc"
         echo "$ALIAS_CCRAW" >> "$rc"
@@ -82,6 +72,6 @@ TMUX_BLOCK
 done
 
 echo "[setup-aliases] Aliases configured:"
-echo "  cc     -> claude with local .claude/system-prompt.md"
-echo "  claude -> claude with local .claude/system-prompt.md"
+echo "  cc     -> claude with \$CLAUDE_CONFIG_DIR/system-prompt.md"
+echo "  claude -> claude with \$CLAUDE_CONFIG_DIR/system-prompt.md"
 echo "  ccraw  -> vanilla claude without any config"

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

@@ -15,6 +15,7 @@ copy_file() {
     if [ -f "$CONFIG_DIR/$file" ]; then
         if [ "$OVERWRITE" = "true" ] || [ ! -f "$TARGET_DIR/$file" ]; then
             cp "$CONFIG_DIR/$file" "$TARGET_DIR/$file"
+            chown "$(id -un):$(id -gn)" "$TARGET_DIR/$file" 2>/dev/null || true
             echo "[setup-config] Copied $file"
         else
             echo "[setup-config] $file already exists, skipping"
@@ -23,6 +24,7 @@ copy_file() {
 }
 
 copy_file "settings.json"
+copy_file "keybindings.json"
 copy_file "main-system-prompt.md"
 
 echo "[setup-config] Configuration complete"

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

@@ -1,5 +1,21 @@
 #!/bin/bash
-# Install plugins: official Anthropic + local devs-marketplace
+# Install plugins: official Anthropic + local devs-marketplace registration
+#
+# Individual marketplace plugins are enabled via enabledPlugins in settings.json.
+# This script only handles:
+# 1. Official Anthropic plugin installs (not managed by enabledPlugins)
+# 2. Local marketplace registration (so Claude Code can discover devs-marketplace)
+
+# Source .env for PLUGIN_BLACKLIST if not already set (e.g., standalone invocation)
+if [ -z "${PLUGIN_BLACKLIST+x}" ]; then
+    SCRIPT_DIR_INIT="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    ENV_FILE="${SCRIPT_DIR_INIT}/../.env"
+    if [ -f "$ENV_FILE" ]; then
+        set -a
+        source "$ENV_FILE"
+        set +a
+    fi
+fi
 
 echo "[setup-plugins] Installing plugins..."
 
@@ -18,33 +34,13 @@ for plugin in "${OFFICIAL_PLUGINS[@]}"; do
     fi
 done
 
-# --- Local Marketplace Plugins ---
+# --- Local Marketplace Registration ---
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 MARKETPLACE_PATH="${SCRIPT_DIR}/../plugins/devs-marketplace"
 
-# Load PLUGIN_BLACKLIST from .env if not already set in environment
-ENV_FILE="${SCRIPT_DIR}/../.env"
-if [ -z "${PLUGIN_BLACKLIST+x}" ] && [ -f "$ENV_FILE" ]; then
-    PLUGIN_BLACKLIST=$(grep -E '^PLUGIN_BLACKLIST=' "$ENV_FILE" | cut -d'=' -f2- | tr -d '"')
-fi
-
-# Parse blacklist into array
-IFS=',' read -ra BLACKLIST <<< "${PLUGIN_BLACKLIST:-}"
-
-# Helper function to check if plugin is blacklisted
-is_blacklisted() {
-    local plugin_name="$1"
-    for blocked in "${BLACKLIST[@]}"; do
-        # Trim whitespace and compare
-        blocked="${blocked// /}"
-        if [ "$plugin_name" = "$blocked" ]; then
-            return 0
-        fi
-    done
-    return 1
-}
-
 # Add local marketplace (if not already added)
+# This is still needed so Claude Code can discover devs-marketplace plugins
+# listed in enabledPlugins in settings.json
 if ! claude plugin marketplace list 2>/dev/null | grep -q "devs-marketplace"; then
     echo "[setup-plugins] Adding devs-marketplace..."
     claude plugin marketplace add "$MARKETPLACE_PATH" 2>/dev/null || {
@@ -52,29 +48,25 @@ if ! claude plugin marketplace list 2>/dev/null | grep -q "devs-marketplace"; th
     }
 fi
 
-# Install ALL plugins from marketplace.json (dynamic discovery)
-MARKETPLACE_JSON="$MARKETPLACE_PATH/.claude-plugin/marketplace.json"
-if [ -f "$MARKETPLACE_JSON" ]; then
-    PLUGINS=$(jq -r '.plugins[].name' "$MARKETPLACE_JSON" 2>/dev/null)
+# --- Install/Update devs-marketplace plugins (syncs cache from source) ---
+# enabledPlugins in settings.json controls enabled/disabled state, but plugins
+# must be explicitly installed to populate the cache. This loop ensures the
+# cache stays in sync with the source directory on every container start.
+if [ -d "$MARKETPLACE_PATH/plugins" ]; then
+    for plugin_dir in "$MARKETPLACE_PATH"/plugins/*/; do
+        plugin_name=$(basename "$plugin_dir")
 
-    if [ -z "$PLUGINS" ]; then
-        echo "[setup-plugins] WARNING: No plugins found in marketplace.json"
-    else
-        for plugin in $PLUGINS; do
-            if is_blacklisted "$plugin"; then
-                echo "[setup-plugins] Skipping $plugin (blacklisted)"
-                continue
-            fi
-            echo "[setup-plugins] Installing $plugin from devs-marketplace..."
-            if claude plugin install "${plugin}@devs-marketplace" 2>/dev/null; then
-                echo "[setup-plugins] Installed: $plugin"
-            else
-                echo "[setup-plugins] WARNING: Failed to install $plugin (may already be installed)"
-            fi
-        done
-    fi
-else
-    echo "[setup-plugins] WARNING: marketplace.json not found at $MARKETPLACE_JSON"
+        # Skip blacklisted plugins
+        if echo ",$PLUGIN_BLACKLIST," | grep -q ",$plugin_name,"; then
+            echo "[setup-plugins] Skipping $plugin_name (blacklisted)"
+            continue
+        fi
+
+        echo "[setup-plugins] Installing $plugin_name@devs-marketplace..."
+        claude plugin install "$plugin_name@devs-marketplace" 2>/dev/null || {
+            echo "[setup-plugins] Warning: Failed to install $plugin_name"
+        }
+    done
 fi
 
 echo "[setup-plugins] Plugin installation complete"