cortexhawk 3.3.0 → 3.3.2

package/scripts/snapshot.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# snapshot.sh — CortexHawk snapshot creation and rotation
+# Sourced by install.sh when --snapshot is used
+# Uses shared functions: sed_inplace, compute_checksum (via manifest)
+# Uses globals: GLOBAL, TARGET, PORTABLE_MODE, PROFILE_FILE, MAX_SNAPSHOTS
+
+# --- rotate_snapshots() ---
+# Keeps only the N most recent snapshots, deletes the rest
+rotate_snapshots() {
+    local snap_dir="$1"
+    local snaps
+    snaps=$(find "$snap_dir" -maxdepth 1 -name '*.json' -type f 2>/dev/null)
+    [ -z "$snaps" ] && return 0
+    local count
+    count=$(echo "$snaps" | wc -l | tr -d ' ')
+    if [ "$count" -gt "$MAX_SNAPSHOTS" ]; then
+        local to_delete=$((count - MAX_SNAPSHOTS))
+        ls -1t "$snap_dir"/*.json | tail -n "$to_delete" | while read -r old_snap; do
+            rm -f "$old_snap"
+        done
+        echo "  Rotated: removed $to_delete old snapshot(s), keeping $MAX_SNAPSHOTS"
+    fi
+}
+
+# --- do_snapshot() ---
+do_snapshot() {
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    local manifest="$TARGET/.cortexhawk-manifest"
+    if [ ! -f "$manifest" ]; then
+        echo "Error: no CortexHawk manifest found at $manifest"
+        echo "Run install.sh first to create an installation"
+        exit 1
+    fi
+
+    # Read manifest metadata
+    local version
+    version=$(grep '"version"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local profile
+    profile=$(grep '"profile"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local source_type
+    source_type=$(grep '"source"' "$manifest" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local source_url
+    source_url=$(grep '"source_url"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+    local source_path
+    source_path=$(grep '"source_path"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+
+    # Read settings.json
+    local settings_json="null"
+    if [ -f "$TARGET/settings.json" ]; then
+        settings_json=$(cat "$TARGET/settings.json")
+    fi
+
+    # Read git-workflow.conf
+    local git_branching="" git_commit="" git_pr="" git_push=""
+    if [ -f "$TARGET/git-workflow.conf" ]; then
+        git_branching=$(grep '^BRANCHING=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        git_commit=$(grep '^COMMIT_CONVENTION=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        git_pr=$(grep '^PR_PREFERENCE=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+        git_push=$(grep '^AUTO_PUSH=' "$TARGET/git-workflow.conf" | cut -d= -f2)
+    fi
+
+    # Read custom profile if applicable (use PROFILE_FILE from current run, never glob /tmp/)
+    local profile_def="null"
+    if [ -n "$PROFILE_FILE" ] && [ -f "$PROFILE_FILE" ]; then
+        profile_def=$(cat "$PROFILE_FILE")
+    fi
+
+    # Build files checksums from manifest
+    local files_json
+    files_json=$(sed -n '/"files"/,/^  }/p' "$manifest" | sed '1d;$d')
+
+    # Collect file contents (base64 encoded for binary safety)
+    local git_workflow_content="" claude_md_content=""
+    if [ -f "$TARGET/git-workflow.conf" ]; then
+        git_workflow_content=$(base64 < "$TARGET/git-workflow.conf" | tr -d '\n')
+    fi
+    if [ -f "$TARGET/../CLAUDE.md" ]; then
+        claude_md_content=$(base64 < "$TARGET/../CLAUDE.md" | tr -d '\n')
+    fi
+
+    # Generate snapshot
+    local now
+    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    local snap_name
+    snap_name=$(date -u +"%Y-%m-%d-%H%M%S")
+    local snap_dir="$TARGET/.cortexhawk-snapshots"
+    local snap_file="$snap_dir/${snap_name}.json"
+
+    mkdir -p "$snap_dir"
+
+    # Write snapshot JSON
+    printf '{\n' > "$snap_file"
+    printf '  "snapshot_version": "2",\n' >> "$snap_file"
+    printf '  "snapshot_date": "%s",\n' "$now" >> "$snap_file"
+    printf '  "cortexhawk_version": "%s",\n' "$version" >> "$snap_file"
+    printf '  "target": "claude",\n' >> "$snap_file"
+    printf '  "profile": "%s",\n' "$profile" >> "$snap_file"
+    printf '  "profile_definition": %s,\n' "$profile_def" >> "$snap_file"
+    printf '  "source": "%s",\n' "$source_type" >> "$snap_file"
+    printf '  "source_url": "%s",\n' "$source_url" >> "$snap_file"
+    printf '  "source_path": "%s",\n' "$source_path" >> "$snap_file"
+    printf '  "settings": %s,\n' "$settings_json" >> "$snap_file"
+    printf '  "git_workflow": {\n' >> "$snap_file"
+    printf '    "BRANCHING": "%s",\n' "$git_branching" >> "$snap_file"
+    printf '    "COMMIT_CONVENTION": "%s",\n' "$git_commit" >> "$snap_file"
+    printf '    "PR_PREFERENCE": "%s",\n' "$git_pr" >> "$snap_file"
+    printf '    "AUTO_PUSH": "%s"\n' "$git_push" >> "$snap_file"
+    printf '  },\n' >> "$snap_file"
+    printf '  "files": {\n' >> "$snap_file"
+    printf '%s\n' "$files_json" >> "$snap_file"
+    printf '  },\n' >> "$snap_file"
+    printf '  "file_contents": {\n' >> "$snap_file"
+    [ -n "$git_workflow_content" ] && printf '    "git-workflow.conf": "%s",\n' "$git_workflow_content" >> "$snap_file"
+    [ -n "$claude_md_content" ] && printf '    "CLAUDE.md": "%s",\n' "$claude_md_content" >> "$snap_file"
+    # Remove trailing comma from last entry
+    sed_inplace '$ s/,$//' "$snap_file"
+    printf '  }\n' >> "$snap_file"
+    printf '}\n' >> "$snap_file"
+
+    echo "CortexHawk Snapshot"
+    echo "====================="
+    echo "  Version:  $version"
+    echo "  Profile:  $profile"
+    echo "  Target:   $TARGET"
+    echo "  Saved to: $snap_file"
+
+    # Create portable archive if requested
+    if [ "$PORTABLE_MODE" = true ]; then
+        local archive_name="${snap_name}.tar.gz"
+        local archive_path="$snap_dir/$archive_name"
+        local tmp_dir
+        tmp_dir=$(mktemp -d)
+
+        # Copy snapshot and files to temp structure
+        cp "$snap_file" "$tmp_dir/snapshot.json"
+        mkdir -p "$tmp_dir/files"
+        cp -r "$TARGET/agents" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/commands" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/skills" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/hooks" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/modes" "$tmp_dir/files/" 2>/dev/null || true
+        cp -r "$TARGET/mcp" "$tmp_dir/files/" 2>/dev/null || true
+        cp "$TARGET/settings.json" "$tmp_dir/files/" 2>/dev/null || true
+        cp "$TARGET/git-workflow.conf" "$tmp_dir/files/" 2>/dev/null || true
+
+        # Create archive
+        tar -czf "$archive_path" -C "$tmp_dir" .
+        rm -rf "$tmp_dir"
+
+        echo "  Archive:  $archive_path"
+        echo ""
+        echo "Restore with: install.sh --restore $archive_path"
+    else
+        rotate_snapshots "$snap_dir"
+        echo ""
+        echo "Restore with: install.sh --restore $snap_file"
+    fi
+}

package/scripts/update.sh

@@ -0,0 +1,280 @@
+#!/bin/bash
+# update.sh — CortexHawk update flow
+# Sourced by install.sh when --update is used
+# Uses shared functions: detect_source_type, get_version, do_snapshot, update_source_git,
+#   update_source_release, compute_checksum, sync_all_components, generate_hooks_config,
+#   write_manifest, run_audit, update_gitignore, setup_templates, cleanup_update
+
+do_update() {
+    # 1. Validate target
+    if [ "$TARGET_CLI" != "claude" ]; then
+        echo "Error: --update is currently supported for Claude Code only"
+        echo "For Kimi CLI, re-run: install.sh --target kimi"
+        exit 1
+    fi
+
+    if [ "$GLOBAL" = true ]; then
+        TARGET="$HOME/.claude"
+    else
+        TARGET="$(pwd)/.claude"
+    fi
+
+    if [ ! -d "$TARGET" ]; then
+        echo "Error: no CortexHawk installation found at $TARGET"
+        echo "Run install.sh without --update for a fresh install"
+        exit 1
+    fi
+
+    # 2. Read manifest
+    local manifest="$TARGET/.cortexhawk-manifest"
+    local current_version="unknown"
+    local current_profile="all"
+    local source_type
+    source_type=$(detect_source_type)
+
+    if [ -f "$manifest" ]; then
+        current_version=$(grep '"version"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        current_profile=$(grep '"profile"' "$manifest" | sed 's/.*: *"\([^"]*\)".*/\1/')
+        local manifest_source
+        manifest_source=$(grep '"source"' "$manifest" | head -1 | sed 's/.*: *"\([^"]*\)".*/\1/')
+        # Only trust manifest's "git" source if SCRIPT_DIR is actually a git repo
+        if [ -n "$manifest_source" ]; then
+            if [ "$manifest_source" = "git" ] && git -C "$SCRIPT_DIR" rev-parse --git-dir >/dev/null 2>&1; then
+                source_type="git"
+            elif [ "$manifest_source" != "git" ]; then
+                source_type="$manifest_source"
+            fi
+        fi
+    else
+        echo "  No manifest found — treating as pre-update installation"
+    fi
+
+    # 3. Profile override
+    local update_profile="$current_profile"
+    if [ -n "$PROFILE" ]; then
+        update_profile="$PROFILE"
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "CortexHawk Dry Run (update)"
+        echo "============================"
+    else
+        echo "CortexHawk Update"
+        echo "==================="
+    fi
+    echo "  Current version: $current_version"
+    echo "  Profile: $update_profile"
+    echo "  Source: $source_type"
+    echo ""
+
+    # 3b. Auto-snapshot before update (skip in dry-run)
+    if [ "$DRY_RUN" != true ] && [ -f "$manifest" ]; then
+        echo "Creating pre-update snapshot..."
+        do_snapshot || echo "  Warning: pre-update snapshot failed — continuing without rollback point"
+        PRE_UPDATE_SNAP=$(ls -t "$TARGET/.cortexhawk-snapshots"/*.json 2>/dev/null | head -1)
+        [ -n "$PRE_UPDATE_SNAP" ] && echo "  Saved: $(basename "$PRE_UPDATE_SNAP")"
+        echo ""
+    fi
+
+    # 4. Pull source (skip in dry-run — compare against current source)
+    if [ "$DRY_RUN" != true ]; then
+        if [ "$source_type" = "git" ]; then
+            echo "Updating CortexHawk source via git pull..."
+            update_source_git
+        else
+            echo "Updating CortexHawk source via download..."
+            update_source_release
+        fi
+        echo "  Source updated successfully."
+    fi
+
+    # 5. Compare versions
+    local new_version
+    new_version=$(get_version)
+    echo "  New version: $new_version"
+    echo ""
+
+    if [ "$current_version" = "$new_version" ] && [ "$FORCE_MODE" != true ]; then
+        # Same version — check if files actually changed (checksum comparison)
+        local files_changed=0
+        if [ -f "$manifest" ]; then
+            while IFS= read -r line; do
+                local fpath fhash
+                fpath=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:\([^"]*\)".*/\1/')
+                fhash=$(echo "$line" | sed 's/.*"sha256:\([^"]*\)".*/\1/')
+                [ -z "$fpath" ] || [ -z "$fhash" ] && continue
+                local source_file="$SCRIPT_DIR/$fpath"
+                [ -f "$source_file" ] || continue
+                local source_hash
+                source_hash=$(compute_checksum "$source_file")
+                if [ "$fhash" != "$source_hash" ]; then
+                    files_changed=$((files_changed + 1))
+                fi
+            done < <(grep '"sha256:' "$manifest")
+        fi
+
+        if [ "$files_changed" -eq 0 ] && [ "$DRY_RUN" != true ]; then
+            # Still apply install improvements even if no component files changed
+            local target_dir_name=".${TARGET_CLI:-claude}"
+            update_gitignore "$(dirname "$TARGET")" "$target_dir_name"
+            [ "$TARGET_CLI" = "codex" ] && update_gitignore "$(dirname "$TARGET")" ".agents"
+            if [ ! -f "$TARGET/git-workflow.conf" ]; then
+                GIT_BRANCHING="direct-main"
+                GIT_COMMIT_CONVENTION="conventional"
+                GIT_PR_PREFERENCE="on-demand"
+                GIT_AUTO_PUSH="after-commit"
+                GIT_WORK_BRANCH=""
+                source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$(dirname "$TARGET")" "$TARGET"
+            fi
+            echo "Already up to date ($new_version). No component files changed."
+            cleanup_update
+            exit 0
+        elif [ "$files_changed" -gt 0 ]; then
+            echo "  Same version ($new_version) but $files_changed file(s) changed in source."
+        fi
+    fi
+
+    if [ "$DRY_RUN" = true ]; then
+        echo "  Comparing source $new_version vs installed $current_version"
+    elif [ "$current_version" = "$new_version" ]; then
+        echo "  Syncing changed files ($new_version)..."
+    else
+        echo "  Updating $current_version -> $new_version"
+    fi
+    echo ""
+
+    # Set up profile file for skill filtering
+    if [ -n "$update_profile" ] && [ "$update_profile" != "all" ]; then
+        PROFILE_FILE="$SCRIPT_DIR/profiles/${update_profile}.json"
+        if [ ! -f "$PROFILE_FILE" ]; then
+            echo "  Warning: profile '$update_profile' not found in source — installing all skills"
+            update_profile="all"
+            PROFILE_FILE=""
+        fi
+    fi
+
+    # 6. Reset counters and sync components
+    SYNC_ADDED=0
+    SYNC_UPDATED=0
+    SYNC_UNCHANGED=0
+    SYNC_SKIPPED=0
+    SYNC_CONFLICTS=0
+
+    sync_all_components "$update_profile"
+
+    # 6b. Sync agent personas from project root
+    local project_root
+    project_root="$(dirname "$TARGET")"
+    if [ -d "$project_root/.cortexhawk-agents" ] && [ "$DRY_RUN" != true ]; then
+        cp -r "$project_root/.cortexhawk-agents/"*.md "$TARGET/agents/" 2>/dev/null || true
+        local pc
+        pc=$(find "$project_root/.cortexhawk-agents" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+        [ "$pc" -gt 0 ] && echo "  Synced $pc agent persona(s) from .cortexhawk-agents/"
+    fi
+
+    # 7. Detect removed upstream files
+    if [ -f "$manifest" ]; then
+        while IFS= read -r line; do
+            local file_relpath
+            file_relpath=$(echo "$line" | sed 's/.*"\([^"]*\)": "sha256:.*/\1/')
+            [ -z "$file_relpath" ] && continue
+            if [ ! -f "$SCRIPT_DIR/$file_relpath" ] && [ -f "$TARGET/$file_relpath" ]; then
+                echo "  Warning: $file_relpath was removed upstream (kept locally)"
+            fi
+        done < <(grep '"sha256:' "$manifest")
+    fi
+
+    if [ "$DRY_RUN" != true ]; then
+        # Make executable components executable
+        for entry in "${COMPONENTS[@]}"; do
+            IFS=':' read -r name exec_flag <<< "$entry"
+            [ "$exec_flag" = "yes" ] && chmod +x "$TARGET/$name/"*.sh 2>/dev/null || true
+        done
+
+        # 7b. Regenerate settings.json hooks + merge new permissions from compose.yml
+        if [ -f "$SCRIPT_DIR/hooks/compose.yml" ]; then
+            local hooks_json
+            hooks_json=$(generate_hooks_config "$SCRIPT_DIR/hooks/compose.yml" ".claude/hooks")
+            if [ -n "$hooks_json" ] && [ "$hooks_json" != "{}" ] && command -v python3 >/dev/null 2>&1; then
+                echo "$hooks_json" | python3 -c "
+import json, sys
+hooks = json.load(sys.stdin)
+current = {}
+try:
+    with open(sys.argv[1]) as f:
+        current = json.load(f)
+except:
+    pass
+current['hooks'] = hooks
+# Merge new permissions from source
+try:
+    with open(sys.argv[2]) as f:
+        src_perms = json.load(f).get('permissions', {})
+    cur_perms = current.get('permissions', {})
+    for key in ('allow', 'deny'):
+        src_list = src_perms.get(key, [])
+        cur_list = cur_perms.get(key, [])
+        added = [p for p in src_list if p not in cur_list]
+        if added:
+            cur_list.extend(added)
+        cur_perms[key] = cur_list
+    current['permissions'] = cur_perms
+except:
+    pass
+with open(sys.argv[1], 'w') as f:
+    json.dump(current, f, indent=2)
+    f.write('\n')
+" "$TARGET/settings.json" "$SCRIPT_DIR/settings.json"
+                echo "  Regenerated settings.json hooks from compose.yml"
+            fi
+        fi
+
+        # 8. Write new manifest
+        write_manifest "$TARGET" "$update_profile" "$TARGET_CLI" true
+
+        # 9. Run audit
+        run_audit "$(dirname "$TARGET")"
+
+        # 10. Apply install improvements (gitignore, git-workflow defaults)
+        local target_dir_name=".${TARGET_CLI:-claude}"
+        update_gitignore "$(dirname "$TARGET")" "$target_dir_name"
+        [ "$TARGET_CLI" = "codex" ] && update_gitignore "$(dirname "$TARGET")" ".agents"
+        setup_templates "$(dirname "$TARGET")"
+
+        if [ ! -f "$TARGET/git-workflow.conf" ]; then
+            GIT_BRANCHING="direct-main"
+            GIT_COMMIT_CONVENTION="conventional"
+            GIT_PR_PREFERENCE="on-demand"
+            GIT_AUTO_PUSH="after-commit"
+            GIT_WORK_BRANCH=""
+            source "$SCRIPT_DIR/scripts/git-workflow-init.sh" "$(dirname "$TARGET")" "$TARGET"
+        fi
+    fi
+
+    # 10. Print summary
+    echo ""
+    if [ "$DRY_RUN" = true ]; then
+        echo "Dry run summary:"
+        echo "  Would add:     $SYNC_ADDED"
+        echo "  Would update:  $SYNC_UPDATED"
+        echo "  Unchanged:     $SYNC_UNCHANGED"
+        echo "  Would skip:    $SYNC_SKIPPED"
+        echo "  Conflicts:     $SYNC_CONFLICTS"
+        echo ""
+        echo "No files were modified (dry run)."
+    else
+        echo "Update complete: $current_version -> $new_version"
+        echo "  Added:     $SYNC_ADDED"
+        echo "  Updated:   $SYNC_UPDATED"
+        echo "  Unchanged: $SYNC_UNCHANGED"
+        echo "  Skipped:   $SYNC_SKIPPED"
+        echo "  Conflicts: $SYNC_CONFLICTS"
+        if [ -n "${PRE_UPDATE_SNAP:-}" ]; then
+            echo "  Rollback: install.sh --restore $PRE_UPDATE_SNAP"
+        fi
+        echo ""
+        echo "  To activate: exit your CLI (ctrl+c) and relaunch in this directory."
+    fi
+
+    cleanup_update
+}

package/templates/AGENT.md

@@ -0,0 +1,19 @@
+---
+name: [agent-name]
+description: [One sentence — what this agent does and when to activate it]
+---
+
+# [Agent Name] Agent
+
+You are a [role description].
+
+## Process
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+## Output Format
+[What the agent should produce]
+
+## Rules
+[Constraints and guidelines — 5-7 items max]

package/templates/CLAUDE.md.template

@@ -0,0 +1,41 @@
+# [Project Name]
+
+[One-line description of what the project does]
+
+## Tech Stack
+- **Language**: [e.g., TypeScript, Python]
+- **Framework**: [e.g., Next.js, FastAPI]
+- **Database**: [e.g., PostgreSQL, MongoDB]
+- **Testing**: [e.g., vitest, pytest]
+
+## Structure
+```
+src/
+├── [main directories]
+tests/
+```
+
+## Conventions
+- **Naming**: [files: kebab-case, functions: camelCase, classes: PascalCase]
+- **Commits**: `type(scope): description` (feat, fix, docs, refactor, test, chore)
+- **Branches**: `feature/description`, `fix/description`, `hotfix/description`
+
+## Commands
+- `[dev command]` — Start dev server
+- `[test command]` — Run tests
+- `[build command]` — Build for production
+- `[lint command]` — Run linter
+
+## Architecture Decisions
+- [Key decision 1 and why]
+- [Key decision 2 and why]
+
+## Security
+- No hardcoded secrets — use environment variables
+- Input validation on all endpoints
+- Auth required on all protected routes
+
+## Testing
+- Unit tests for business logic
+- Integration tests for API endpoints
+- Coverage target: [80%]

package/templates/COMMAND.md

@@ -0,0 +1,14 @@
+# /[command-name]
+
+## Purpose
+[One sentence — what this command does]
+
+---
+
+Activate the **[agent-name]** agent. Target: `$ARGUMENTS`
+
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+[Any additional constraints or output format requirements]

package/templates/ORCHESTRATION.md

@@ -0,0 +1,79 @@
+# Agent Orchestration Patterns
+
+## Sequential Pipeline
+
+Run agents one after another, each receiving the previous output.
+
+```
+/plan → planner → plan.md
+/build → implementer → code changes (follows plan.md)
+/test → tester → test results
+/review → reviewer → review report
+/ship → git-manager + reviewer → commit + PR
+```
+
+**Use when**: Feature development from scratch.
+
+## Parallel Execution
+
+Run independent agents simultaneously to save time.
+
+```
+┌─ tester (unit tests)
+plan → implementer ─┤
+                    └─ tester (integration tests)
+```
+
+**Use when**: Test generation can happen in parallel for different scopes.
+
+## Gate Pattern
+
+Agent B only runs if Agent A passes.
+
+```
+reviewer → [pass?] → git-manager → [commit]
+                  → [fail?] → STOP, report issues
+```
+
+**Use when**: `/ship` — don't commit if review finds critical issues.
+
+## Loop Pattern
+
+Repeat until quality gate passes.
+
+```
+implementer → tester → [tests pass?] → done
+                     → [tests fail?] → implementer (fix) → tester → ...
+```
+
+**Use when**: `/tdd` — red-green-refactor cycle.
+
+## Escalation Pattern
+
+Start simple, bring in specialists when needed.
+
+```
+debugger → [found root cause?] → fix
+        → [needs architecture change?] → architect → planner → implementer
+```
+
+**Use when**: `/debug` — simple bugs stay with debugger, complex ones escalate.
+
+## Multi-Agent Review
+
+Multiple agents review the same code from different angles.
+
+```
+       ┌─ reviewer (correctness)
+code ──┼─ security-auditor (security)
+       └─ code-simplifier (complexity)
+```
+
+**Use when**: Pre-release quality gate or critical code paths.
+
+## Rules
+- Each agent receives clear input and produces structured output
+- Gate pattern prevents broken code from progressing
+- Parallel agents must not modify the same files
+- Always define a failure path — what happens when an agent flags issues
+- Keep pipelines ≤5 steps — longer pipelines are harder to debug

package/templates/PERSONA.md

@@ -0,0 +1,17 @@
+---
+name: [persona-name]
+extends: [base-agent-name]
+description: [One sentence — how this persona differs from the base agent]
+---
+
+# [Persona Name]
+
+Custom agent persona extending **[base-agent-name]**.
+
+## Overrides
+
+[Rules, style, or behavior that override or extend the base agent]
+
+## Rules
+
+[Additional rules specific to this persona — these are ADDED to the base agent's rules]

package/templates/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: [skill-name]
+description: [One sentence — when should Claude use this skill?]
+detect: [base | <file> | <file>:<pattern> | dir:<path> — omit if not auto-detectable]
+requires: [category/skill-name — space-separated list of required skills, omit if none]
+---
+
+# [Skill Name]
+
+## [Core Instructions]
+[What Claude should do when this skill is active]
+
+## Examples
+[Concrete code/usage examples]
+
+## Rules
+[Do's and don'ts — keep it to 5-7 items max]

package/templates/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+<!-- What does this PR do and why? -->
+
+## Type
+<!-- Check one -->
+- [ ] Feature
+- [ ] Bug fix
+- [ ] Refactor
+- [ ] Docs
+- [ ] Chore
+
+## Changes
+-
+
+## Test Plan
+- [ ]
+
+## Checklist
+- [ ] Tests pass
+- [ ] No secrets or .env committed
+- [ ] Docs updated (if applicable)
+- [ ] No breaking changes (or documented below)
+
+## Related
+<!-- Link issues, backlog items, or conversations -->
+<!-- Examples: Closes #123 | Backlog #119 | N/A -->

package/templates/github/gitmessage

@@ -0,0 +1,10 @@
+
+# type(scope): subject
+#
+# Types: feat, fix, docs, style, refactor, test, chore, perf, security
+# Scope: optional module/component name
+# Subject: imperative mood, lowercase, no period, max 72 chars
+#
+# Body: explain WHY, not WHAT (the diff shows the what)
+#
+# Footer: BREAKING CHANGE: description | Closes #123 | Backlog #N