forgedock 1.0.4 → 1.0.6

package/templates/devdocs/agent/using-forgedock.md

@@ -0,0 +1,245 @@
+---
+authority: required
+scope: agent
+applies_to: [work-on, review-pr, orchestrate, quality-gate, issue, milestone]
+---
+
+# Using ForgeDock — Authoritative Pipeline Reference
+
+ForgeDock is an autonomous development pipeline for Claude Code. It turns GitHub issues into the persistent context layer — agents investigate, build, review, and merge code with minimal human intervention.
+
+---
+
+## Core Principle
+
+**GitHub issues are the persistent memory.** Every significant action is written back to the issue as a structured comment. If a session is interrupted, the next session re-reads the issue's comments and labels to reconstruct where it left off.
+
+---
+
+## Pipeline Architecture
+
+The `/work-on` command runs the full lifecycle. A single invocation may span multiple Claude sessions — each picks up from the last state.
+
+### Phase Sequence
+
+| Phase | Name | What Happens |
+|-------|------|-------------|
+| 0 | Context Load | Read `forge.yaml`, load issue state, classify lane |
+| 1 | Investigation | Validate the issue, find root cause, read affected files |
+| 2 | Decomposition | (Optional) Split large issues into sub-issues |
+| 3A–3M | Build | Contract → Context → Architecture → Implement → Quality Gate → Commit |
+| 4 | PR Creation | Push branch, create PR targeting the correct base branch |
+| 5 | Auto-Review | Run `/review-pr --auto-merge`; domain agents review; PR merges |
+| 6 | Close & Cleanup | Close issue, update project board, remove worktree |
+| 7 | Trajectory | Post pipeline summary; terminal state |
+
+### Terminal States
+
+The pipeline stops only when one of these labels is present:
+- `workflow:merged` — PR merged, issue closed
+- `workflow:invalid` — issue confirmed as not valid
+- `needs-human` — blocker requires manual intervention
+- `workflow:decomposed` — sub-issues spawned; each runs its own pipeline
+
+---
+
+## Lane Types
+
+Issues route to different PR targets based on their milestone:
+
+| Lane | Trigger | PR Target | Branch Prefix |
+|------|---------|-----------|---------------|
+| **Fast Lane** | Issue has no milestone | `staging` | `fix/` or `feat/` |
+| **Feature Lane** | Issue has a milestone | `milestone/{slug}` | `fix/` or `feat/` |
+
+**Never target `main` directly.** PRs go to `staging` (fast lane) or `milestone/*` (feature lane). Main receives changes only through the staging→main deploy process.
+
+---
+
+## Command Reference
+
+### `/work-on [issue_number]`
+
+Runs the full pipeline for a single issue. Invoke repeatedly until the issue reaches a terminal state.
+
+```bash
+# Pick up specific issue
+/work-on 258
+
+# Pick highest-priority open issue automatically
+/work-on next
+```
+
+**Resume behavior**: If `/work-on` was interrupted, re-invoking it reads the issue's existing comments and labels to determine which phase to resume from. No manual state management needed.
+
+### `/orchestrate [milestone_slug]`
+
+Orchestrates parallel work on an entire milestone — spawns sub-agents, each running `/work-on` for a separate issue.
+
+```bash
+/orchestrate milestone user-auth-v2
+```
+
+### `/review-pr [PR_number]`
+
+Runs a multi-agent code review on a PR. 9 domain agents (API, frontend, security, infra, database, etc.) each review their area. Findings become separate GitHub issues.
+
+```bash
+/review-pr 42
+/review-pr staging   # review the staging→main PR
+```
+
+**Review findings are NOT merge blockers.** They become separate issues to fix in subsequent PRs.
+
+### `/issue [description]`
+
+Creates a well-structured GitHub issue with all mandatory pipeline sections. Reads code before creating the issue to ensure file paths are accurate.
+
+```bash
+/issue the billing page crashes when credits hit zero
+/issue feat: add dark mode toggle to dashboard settings
+```
+
+### `/milestone [action] [name]`
+
+Creates and manages milestones — the top-level planning layer.
+
+```bash
+/milestone create "User Auth v2"
+/milestone ship user-auth-v2
+```
+
+### `/quality-gate [files...]`
+
+Runs automated checks on changed files: dead code, missing error handling, security anti-patterns, performance footguns.
+
+### `/analytics`
+
+Pulls production analytics from configured sources (GSC, GA4, Umami, Clarity, Cloudflare, Stripe). Generates insights and creates actionable GitHub issues.
+
+### `/cleanup`
+
+Sweeps closed issues for stale labels, prunes worktrees, cleans up stale branches.
+
+### `/deploy-info`
+
+Shows what will deploy next — diffs staging vs main with issue/PR summary, risk assessment, and deploy checklist.
+
+### `/audit [issue_or_run]`
+
+Traces a production issue or pipeline failure end-to-end through GitHub artifacts.
+
+### `/audit-agents`
+
+Analyzes agent output from an orchestration run — timeline, stall detection, active vs idle time.
+
+---
+
+## Phase 3 Build Sub-Phases
+
+When building, these sub-phases run in order. Every sub-phase is mandatory:
+
+```
+3A  Re-read issue state from GitHub
+3B  Classify task type (bug/feature/refactor/docs/investigation)
+3C  Post Builder Contract (deliverables, acceptance criteria)
+3C.5  Context gathering (past review findings, related code paths)
+3C.6  Architecture plan (affected paths, implementation order, risk assessment)
+3D  Set workflow:building label
+3E  Create git worktree from source branch
+3F  Implement (follow architect plan; read context before writing code)
+3F.5  Env/config completeness check
+3G  Quality gate (up to 3 iterations to fix findings)
+3H  Format and verify (black/isort/py_compile for Python; prettier/tsc for TypeScript)
+3I  Frontend proxy wiring check (if TypeScript files changed)
+3I.5  Database configuration advisory (if DB engine patterns changed)
+3J  Deployment completeness check (if new env vars introduced)
+3K  Commit (conventional commit message with issue reference)
+3L  Update issue body (check off completed items)
+3M  Post implementation comment (FORGE:BUILDER)
+```
+
+---
+
+## Workflow Labels
+
+Labels track pipeline state. Do not manually modify `workflow:*` labels — the pipeline manages them.
+
+| Label | Meaning |
+|-------|---------|
+| `workflow:investigating` | Phase 1 in progress |
+| `workflow:ready-to-build` | Investigation complete; build queued |
+| `workflow:building` | Phase 3 in progress |
+| `workflow:in-review` | PR created; awaiting review |
+| `workflow:merged` | Pipeline complete; PR merged |
+| `workflow:invalid` | Issue closed as not valid |
+| `workflow:decomposed` | Issue split into sub-issues |
+| `needs-human` | Pipeline stalled; manual action required |
+
+---
+
+## forge.yaml Configuration
+
+`forge.yaml` at the project root configures all pipeline variables. Required sections:
+
+- `project` — GitHub owner, repo name
+- `paths` — local repo root, worktree base directory
+- `branches` — default, staging, feature pattern
+
+Optional sections:
+- `project_board` — GitHub Projects v2 integration
+- `review` — tech stack context for review agents
+- `services` — analytics/monitoring endpoints
+- `repos` — multi-repo satellite routing
+
+Generate or update `forge.yaml`:
+
+```bash
+npx forgedock init        # interactive setup
+npx forgedock docs init   # scaffold devdocs directory
+```
+
+---
+
+## Compaction Resilience
+
+ForgeDock is designed to survive session interruptions:
+
+1. Every significant step writes state to GitHub (comments + labels)
+2. Re-reading the issue at the start of each phase reconstructs all context
+3. A new session can pick up any interrupted pipeline by re-running `/work-on {number}`
+
+**Never rely on in-memory state across phase boundaries.** Read from GitHub.
+
+---
+
+## Multi-Repo Routing
+
+When `forge.yaml → repos.satellites` is configured, issue numbers can be prefixed to route to satellite repos:
+
+```bash
+/work-on mcp:5     # routes to satellite repo with prefix "mcp"
+/work-on sdk:12    # routes to satellite repo with prefix "sdk"
+/work-on 42        # routes to default repo
+```
+
+---
+
+## Idempotency Rules
+
+- Re-invoking `/work-on` on a completed issue is safe — it reads the terminal label and stops
+- Creating a worktree that already exists: the pipeline reuses it
+- Posting a duplicate phase comment: the pipeline checks for existing comments before posting
+- Quality gate running on already-clean code: it passes immediately
+
+---
+
+## Common Troubleshooting
+
+| Symptom | Cause | Resolution |
+|---------|-------|------------|
+| Issue stuck at `workflow:investigating` | Investigation comment missing `<!-- INVESTIGATION:COMPLETE -->` | Re-run `/work-on` — partial comments are detected and deleted |
+| Merge conflict on PR | Branch diverged from base | Post comment, add `needs-human`; never auto-resolve |
+| `needs-human` label set | Pipeline encountered a blocker | Read the issue comments for the specific blocker |
+| Worktree already exists | Previous run was interrupted mid-build | Re-run — worktree is reused if branch is correct |
+| Sub-issue pipeline not started | Parent was decomposed | Run `/work-on {sub_issue_number}` for each sub-issue |

package/templates/devdocs/agent/using-github.md

@@ -0,0 +1,325 @@
+---
+authority: required
+scope: agent
+applies_to: [work-on, review-pr, issue, orchestrate, quality-gate, cleanup]
+---
+
+# Using GitHub — Authoritative Conventions Reference
+
+This document defines how agents and developers interact with GitHub in this project. These conventions ensure the ForgeDock pipeline functions correctly and that the issue/PR/branch graph remains navigable.
+
+---
+
+## Core Principle
+
+**Issues are the unit of work.** Every change — bug fix, feature, refactor — starts as a GitHub issue and ends as a merged PR that closes it. No direct pushes to `main` or `staging`. No PRs without a linked issue (except hotfixes with explicit justification).
+
+---
+
+## GitHub CLI (`gh`) Usage
+
+### Authentication
+
+```bash
+gh auth status          # verify authentication
+gh auth login           # authenticate if needed
+```
+
+### Common Flags
+
+All commands that target a specific repository use the `-R owner/repo` flag. In ForgeDock pipelines, this is resolved from `forge.yaml`:
+
+```bash
+GH_REPO=$(yq '.project.owner + "/" + .project.repo' forge.yaml)
+GH_FLAG="-R $GH_REPO"
+
+# Example usage
+gh issue view 42 $GH_FLAG
+gh pr list $GH_FLAG --state open
+```
+
+---
+
+## Issue Conventions
+
+### Creating Issues
+
+Issues MUST have these four sections for pipeline compatibility:
+
+```markdown
+## Problem
+{1-3 sentences — what is wrong or missing}
+
+## Affected Files
+{numbered list of file paths that need changes}
+
+## Acceptance Criteria
+- [ ] {specific, testable criterion}
+
+## Expected Behavior
+{what should happen after the fix/feature is implemented}
+```
+
+Use the `/issue` command to create issues — it reads code before writing, enforces structure, and checks for duplicates automatically.
+
+### Title Format
+
+```
+{prefix}: {concise description}
+{prefix}({scope}): {concise description}
+```
+
+| Prefix | Use for |
+|--------|---------|
+| `fix:` | Bug fixes |
+| `feat:` | New features |
+| `refactor:` | Code restructuring, no behavior change |
+| `docs:` | Documentation changes |
+| `chore:` | Maintenance (version bumps, CI config) |
+| `investigate:` | Research/audit tasks |
+
+**Max 80 characters.** Be specific: `fix(billing): division by zero when user credits reach 0` not `fix: billing bug`.
+
+### Labels
+
+**Priority labels** (required on all issues):
+
+| Label | When to use |
+|-------|------------|
+| `priority:P0` | Production down, data loss, security vulnerability |
+| `priority:P1` | Significant user-facing bug, deploy blocked |
+| `priority:P2` | Minor bug, non-critical enhancement (default) |
+| `priority:P3` | Cosmetic, nice-to-have, low-impact |
+
+**Category labels** (required, one per issue):
+
+`bug`, `enhancement`, `feature`, `refactor`, `docs`, `infra`, `performance`, `security`, `ux`, `dead-code`, `review-finding`, `audit-finding`
+
+**Workflow labels** (managed by pipeline — do not set manually):
+
+`workflow:investigating`, `workflow:ready-to-build`, `workflow:building`, `workflow:in-review`, `workflow:merged`, `workflow:invalid`, `workflow:decomposed`, `needs-human`
+
+### Checking for Duplicates
+
+Always check before creating:
+
+```bash
+gh issue list $GH_FLAG --state open --search "{keywords}" --limit 20 \
+  --json number,title,labels --jq '.[] | "#\(.number) \(.title)"'
+
+gh issue list $GH_FLAG --state closed --search "{keywords}" --limit 10 \
+  --json number,title --jq '.[] | "#\(.number) [closed] \(.title)"'
+```
+
+---
+
+## Branch Naming
+
+### Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Bug fix | `fix/{slug}-{issue_number}` | `fix/billing-zero-credits-42` |
+| Feature | `feat/{slug}-{issue_number}` | `feat/dark-mode-toggle-58` |
+| Fast lane (any) | `fix/` or `feat/` prefix | (same as above) |
+| Feature lane | `feat/{slug}-{issue_number}` on `milestone/{slug}` branch | — |
+
+**Slug rules**: lowercase, hyphenated, max 40 chars, derived from issue title.
+
+### Source Branch Rules
+
+| Lane | Issue has milestone? | Branch from |
+|------|---------------------|------------|
+| Fast | No | `origin/staging` |
+| Feature | Yes | `origin/milestone/{slug}` |
+| Review-finding | Has `Code branch: \`{branch}\`` in body | `origin/{branch}` |
+
+### Git Worktrees
+
+ForgeDock uses git worktrees for isolation. Each issue gets its own worktree:
+
+```bash
+WORKTREE_PATH="{repo_root}/.claude/worktrees/{branch}"
+git worktree add "$WORKTREE_PATH" -b "{branch}" origin/{source_branch}
+```
+
+**Never work directly in the main repo checkout when a worktree exists.** All file reads, writes, and git operations for an active issue happen in the worktree.
+
+---
+
+## PR Conventions
+
+### Target Branch Rules
+
+| Situation | PR Base |
+|-----------|---------|
+| Fast-lane issue (no milestone) | `staging` |
+| Feature-lane issue (has milestone) | `milestone/{slug}` |
+| **NEVER** | `main` |
+
+`main` receives changes only through the staging review process (`/review-pr staging`).
+
+### PR Body Structure
+
+```markdown
+## Summary
+{1-3 sentences describing what changed and why}
+
+## Changes
+- {file or component}: {what changed}
+- {file or component}: {what changed}
+
+## Testing
+- [ ] {test scenario 1}
+- [ ] {test scenario 2}
+
+---
+Closes #{issue_number}
+**Implementation branch**: `{branch}`
+**Base**: `{pr_base}`
+```
+
+**`Closes #{N}` does not auto-close** for non-default-branch PRs. The pipeline explicitly closes the issue after merge.
+
+### PR Title Format
+
+```
+{Fix|Feat|Refactor|Docs}: {description}
+```
+
+Capitalize the prefix. Match the issue prefix. Examples:
+- `Fix: billing division by zero when user credits reach 0`
+- `Feat: dark mode toggle for dashboard settings`
+
+---
+
+## Commit Conventions
+
+### Format
+
+```
+{type}({scope}): {description} (#{issue_number})
+```
+
+| Field | Rules |
+|-------|-------|
+| `type` | `fix`, `feat`, `refactor`, `docs`, `chore`, `test` |
+| `scope` | optional; component name in parentheses |
+| `description` | imperative mood, lowercase, no period, under 72 chars |
+| `#{issue_number}` | always reference the issue |
+
+### Examples
+
+```
+fix(billing): prevent division by zero when user credits reach 0 (#42)
+feat(dashboard): add dark mode toggle to settings page (#58)
+refactor(api): extract pagination logic into shared utility (#71)
+docs(config): document devdocs frontmatter authority field (#258)
+chore: bump version to 1.2.0 [skip ci]
+```
+
+### Multi-line Commits
+
+When more context is needed:
+
+```
+fix(api): handle null response from external payment provider (#99)
+
+The Stripe webhook handler did not handle the case where the payment
+provider returns a null payment_intent. Added null guard and fallback
+to pending state with retry scheduling.
+```
+
+### Rules
+
+- **Imperative mood**: "add" not "added", "fix" not "fixed"
+- **No period** at the end
+- **Under 72 characters** on the first line
+- **Always reference the issue**: `(#{N})`
+- **`[skip ci]`**: only for pure documentation or version bump commits
+
+---
+
+## Label Management
+
+### Creating Missing Labels
+
+```bash
+gh label create "workflow:investigating" --color "1D76DB" -R $GH_REPO
+gh label create "priority:P2" --color "FBCA04" -R $GH_REPO
+gh label create "review-finding" --color "D93F0B" -R $GH_REPO
+```
+
+### Bulk Label Sync
+
+Use `/cleanup` to sweep for stale labels, missing workflow states, and project board gaps.
+
+---
+
+## Project Board Integration
+
+ForgeDock commands automatically update the GitHub Projects v2 board when `project_board` is configured in `forge.yaml`. Status moves through: Todo → In Progress → Done.
+
+To manually add an issue to the board:
+
+```bash
+gh project item-add {project_number} --owner {owner} --url "{issue_url}"
+```
+
+---
+
+## Common gh CLI Patterns
+
+### View Issue with Comments
+
+```bash
+gh issue view {number} $GH_FLAG --json number,title,body,labels,state,comments
+gh api repos/{GH_REPO}/issues/{number}/comments \
+  --jq '.[] | {id: .id, author: .user.login, body: (.body | .[0:200])}'
+```
+
+### Find PRs for a Branch
+
+```bash
+gh pr list $GH_FLAG --head {branch} --json number,state,title
+```
+
+### Close Issue with Comment
+
+```bash
+gh issue close {number} $GH_FLAG \
+  --comment "Closed: PR #{pr_number} merged to \`{base}\`. Closes #{number}."
+```
+
+### Merge PR
+
+```bash
+gh pr merge {pr_number} $GH_FLAG --merge --auto
+```
+
+### Check PR Status
+
+```bash
+gh pr view {pr_number} $GH_FLAG --json state,mergedAt,mergeable,mergeStateStatus \
+  --jq '{state, mergedAt, mergeable, mergeStateStatus}'
+```
+
+### Edit Issue Labels
+
+```bash
+gh issue edit {number} $GH_FLAG \
+  --add-label "workflow:building" \
+  --remove-label "workflow:ready-to-build"
+```
+
+---
+
+## Safety Rules
+
+1. **Never push to `main` directly.** Even hotfixes go through a PR.
+2. **Never force-push to shared branches** (`main`, `staging`, `milestone/*`) without explicit human approval.
+3. **Never use `--no-verify`** to skip hooks unless explicitly asked.
+4. **Always check mergeability** before posting a review verdict: `gh pr view {N} --json mergeable,mergeStateStatus`.
+5. **Never create duplicate issues.** Check open AND closed issues before creating.
+6. **Never fabricate file paths.** Verify with `git show origin/{branch}:{filepath}` before listing a file in an issue.
+7. **Review findings are NOT merge blockers.** They become separate issues to fix later.

package/templates/devdocs/project/architecture.md

@@ -0,0 +1,122 @@
+---
+authority: required
+scope: project
+applies_to: [work-on, review-pr, issue, orchestrate]
+---
+
+# System Architecture
+
+This file describes the system architecture and domain organization for this project. Pipeline agents read this file to understand how components relate, where boundaries lie, and which files belong to which domain.
+
+---
+
+## Instructions
+
+Replace the placeholder content below with your project's actual architecture. Be specific about:
+- Service/layer boundaries (what each component owns)
+- Data flows (how data moves between components)
+- Domain file locations (where to find code for each domain)
+
+---
+
+## High-Level Architecture
+
+> Describe the system at a high level. What are the major components and how do they interact?
+
+```
+{e.g.:
+Frontend (Next.js)
+    ↓ /api/* proxy
+API Service (FastAPI)
+    ↓                    ↓
+PostgreSQL            Redis
+                         ↓
+                    Worker Service (Celery)
+                         ↓
+                    External APIs (Stripe, etc.)
+}
+```
+
+**Key architectural decisions**:
+- {e.g., "All external API calls are proxied through the API service — the frontend never calls third-party APIs directly"}
+- {e.g., "Workers and API share the same database but have separate connection pools"}
+- {e.g., "Deploy uses blue/green — two containers run simultaneously during deploy, Traefik switches traffic"}
+
+---
+
+## Domains and File Locations
+
+> Map each domain to its directory structure. Agents use this to find the right files quickly.
+
+### {Domain 1, e.g., "Authentication"}
+
+**Responsibility**: {What this domain owns — be specific}
+**Location**: `{e.g., services/api/app/auth/}`
+**Key files**:
+- `{filepath}` — {what it does}
+- `{filepath}` — {what it does}
+
+### {Domain 2, e.g., "Billing & Subscriptions"}
+
+**Responsibility**: {What this domain owns}
+**Location**: `{e.g., services/api/app/billing/}`
+**Key files**:
+- `{filepath}` — {what it does}
+- `{filepath}` — {what it does}
+
+### {Domain 3, e.g., "Frontend — Dashboard"}
+
+**Responsibility**: {What this domain owns}
+**Location**: `{e.g., web/src/app/dashboard/}`
+**Key files**:
+- `{filepath}` — {what it does}
+
+---
+
+## Data Flow
+
+> Describe how data moves through the system for the most important operations.
+
+### {Key operation, e.g., "User creates a subscription"}
+
+```
+1. Frontend: POST /api/subscriptions
+2. API: Validate request → call Stripe
+3. Stripe: Returns subscription object
+4. API: Write to PostgreSQL (subscriptions table)
+5. API: Publish event to Redis queue
+6. Worker: Consume event → send confirmation email
+```
+
+---
+
+## Deployment Architecture
+
+> How does the system deploy in production?
+
+**Environment**: {e.g., single VPS, multi-region, serverless}
+**Containers**: {e.g., api-blue, api-green, web, worker, postgres, redis, traefik}
+**Deploy process**: {e.g., "GitHub Actions SSH → pull latest → docker compose up --force-recreate"}
+**Database**: {e.g., "PostgreSQL in Docker with named volume; backups to S3 daily"}
+**Secrets**: {e.g., "SOPS-encrypted secrets in infra/secrets/prod.enc.yaml; decrypted by deploy script"}
+
+---
+
+## Cross-Domain Constraints for Agents
+
+> Rules that apply across domain boundaries — agents must follow these when building.
+
+- {e.g., "Services never import from each other — communication is through the database or queue only"}
+- {e.g., "Frontend components in `components/ui/` are shared across authenticated and public routes — never add auth-dependent hooks without a null-context guard"}
+- {e.g., "All cross-service events must be idempotent — workers may process the same message more than once"}
+- {e.g., "Database schema changes require a migration file — never modify the schema directly"}
+
+---
+
+## Known Architectural Footguns
+
+> Document recurring patterns that cause bugs in this codebase. Agents read this before investigating and building.
+
+- {e.g., "Docker named volumes are created as root-owned — always chown in the entrypoint before privilege drop"}
+- {e.g., "The frontend dev server proxies /api/* to port 8000, but production uses Traefik — never hardcode ports in frontend code"}
+- {e.g., "`appleboy/ssh-action` preprocesses `{{` as Go templates before SSH — use `jq` instead of docker format strings"}