agentic-swe 1.0.0

package/.claude/phases/subagent-selection.md

@@ -0,0 +1,298 @@
+# Subagent Auto-Selection Policy
+
+## Mission
+
+Automatically select and spawn specialized subagents during pipeline execution based on evidence from the task, repository, and affected files. Selection is deterministic, evidence-based, and supplementary to core pipeline agents.
+
+This policy is consulted by the orchestrator and by core agents (developer.md, panel agents) at specific points during phase execution. Subagents run in the background and are advisory — the orchestrator or calling agent owns the final decision.
+
+---
+
+## When This Policy Is Consulted
+
+| Phase | Trigger | Who Reads This | Purpose |
+|-------|---------|----------------|---------|
+| feasibility | After `/repo-scan` completes | Orchestrator | Collect signals, write `## Subagent Signals` into feasibility.md |
+| fast-implementation | Before spawning developer.md | Orchestrator | Optionally spawn 1 language specialist (background, non-blocking) |
+| implementation | Before spawning developer.md | Orchestrator | Spawn language + domain specialists (background, advisory) |
+| design | Before panel invocation | Orchestrator | Spawn domain specialist for pre-design input |
+| code-review | After reading artifacts | Orchestrator | Spawn specialized reviewers in parallel |
+| (any agent work) | When agent detects domain-specific need | developer.md, panel agents | Agent-to-agent delegation |
+
+---
+
+## Signal Collection (Feasibility Phase)
+
+After `/repo-scan` completes, extract signals from three sources and write them into the feasibility artifact as a `## Subagent Signals` section.
+
+### Source 1: Repo-scan output
+
+- `Languages` field → language specialist candidates
+- `Frameworks` / `Dependencies` fields → framework specialist candidates
+- `Test frameworks`, `CI/CD`, `Linters` → tooling signals
+
+### Source 2: Task description and feasibility observations
+
+- Domain keywords (security, payments, ML, infrastructure, etc.)
+- Affected subsystems and their nature
+
+### Source 3: File paths in scope
+
+- File extensions of files likely to be changed
+- Directory patterns (`infra/`, `terraform/`, `k8s/`, `ml/`, `auth/`, etc.)
+
+### Output format
+
+Write into `feasibility.md`:
+
+```markdown
+## Subagent Signals
+
+- **Primary language**: <language> (<confidence>)
+- **Framework**: <framework> (<confidence>)
+- **Domain signals**: <keyword list from task/paths>
+- **Recommended subagents**:
+  - <agent-name> (<role>: language|framework|domain, <confidence>)
+  - <agent-name> (<role>, <confidence>)
+- **Subagent mode**: full | minimal
+```
+
+Set `subagent mode` to `minimal` if fast-path-check routes to fast path, `full` otherwise.
+
+---
+
+## Selection Rules
+
+### Language Specialist Mapping
+
+| Signal | Subagent | Confidence |
+|--------|----------|------------|
+| Python (.py), pyproject.toml, setup.py | `python-pro` | high |
+| TypeScript (.ts, .tsx), tsconfig.json | `typescript-pro` | high |
+| JavaScript (.js, .jsx) without TypeScript | `javascript-pro` | high |
+| Rust (.rs), Cargo.toml | `rust-engineer` | high |
+| Go (.go), go.mod | `golang-pro` | high |
+| Java (.java), pom.xml, build.gradle | `java-architect` | high |
+| C++ (.cpp, .cc, .h), CMakeLists.txt | `cpp-pro` | high |
+| C# (.cs), *.csproj | `csharp-developer` | high |
+| PHP (.php), composer.json | `php-pro` | high |
+| Ruby (.rb), Gemfile | `rails-expert` | medium |
+| Swift (.swift), Package.swift | `swift-expert` | high |
+| Kotlin (.kt), build.gradle.kts | `kotlin-specialist` | high |
+| Elixir (.ex, .exs), mix.exs | `elixir-expert` | high |
+| SQL (.sql) as primary change surface | `sql-pro` | medium |
+| PowerShell (.ps1, .psm1) | `powershell-7-expert` | high |
+
+### Framework Specialist Mapping
+
+| Signal | Subagent | Confidence |
+|--------|----------|------------|
+| React / react-dom in dependencies | `react-specialist` | high |
+| Next.js / next in dependencies | `nextjs-developer` | high |
+| Vue / vue in dependencies | `vue-expert` | high |
+| Angular / @angular/core | `angular-architect` | high |
+| Django in dependencies | `django-developer` | high |
+| FastAPI in dependencies | `fastapi-developer` | high |
+| Rails in Gemfile | `rails-expert` | high |
+| Spring Boot in dependencies | `spring-boot-engineer` | high |
+| Laravel in composer.json | `laravel-specialist` | high |
+| Flutter / pubspec.yaml | `flutter-expert` | high |
+| React Native + Expo | `expo-react-native-expert` | high |
+| Electron in dependencies | `electron-pro` | high |
+| Symfony in composer.json | `symfony-specialist` | high |
+| .NET Core / Microsoft.NET.Sdk | `dotnet-core-expert` | high |
+| Svelte / SvelteKit | `svelte-developer` | medium |
+
+### Domain Specialist Mapping
+
+| Signal Pattern (keywords in task, paths, feasibility) | Subagent | When to use |
+|-------------------------------------------------------|----------|-------------|
+| terraform/, .tf files, "infrastructure as code" | `terraform-engineer` | Infra changes |
+| Dockerfile, docker-compose, container | `docker-expert` | Container work |
+| k8s/, kubernetes, helm charts | `kubernetes-specialist` | K8s orchestration |
+| CI/CD, pipeline, GitHub Actions, Jenkins | `devops-engineer` | Pipeline changes |
+| AWS, CloudFormation, CDK | `cloud-architect` | Cloud architecture |
+| Azure, Bicep, Entra | `azure-infra-engineer` | Azure infra |
+| "security", "auth", RBAC, OAuth, JWT | `security-auditor` | Security-sensitive code |
+| "performance", "latency", "throughput" | `performance-engineer` | Performance work |
+| "accessibility", "a11y", WCAG | `accessibility-tester` | A11y changes |
+| "machine learning", "model training", ML | `ml-engineer` | ML pipeline code |
+| "LLM", "prompt", "embedding", "RAG" | `llm-architect` | LLM/AI systems |
+| "data pipeline", ETL, "data warehouse" | `data-engineer` | Data infrastructure |
+| PostgreSQL specifically | `postgres-pro` | Postgres-specific work |
+| "database", "migration", "schema" | `database-administrator` | DB schema changes |
+| "API design", "REST", "OpenAPI" | `api-designer` | API surface changes |
+| GraphQL schema changes | `graphql-architect` | GraphQL work |
+| "microservice", "service mesh" | `microservices-architect` | Service boundaries |
+| "WebSocket", "real-time", "streaming" | `websocket-engineer` | Real-time features |
+| "blockchain", "smart contract", "web3" | `blockchain-developer` | Web3 work |
+| "payment", "stripe", "billing", PCI | `payment-integration` | Payment integration |
+| "CLI", "command-line tool" | `cli-developer` | CLI development |
+| "refactor", "legacy", "modernize" | `refactoring-specialist` | Large refactors |
+| "documentation", "docs site" | `documentation-engineer` | Docs overhaul |
+| MCP, "model context protocol" | `mcp-developer` | MCP tool development |
+| Game engine, Unity, rendering | `game-developer` | Game development |
+| IoT, edge computing, firmware | `iot-engineer` | IoT/embedded work |
+| "fintech", financial compliance | `fintech-engineer` | Financial systems |
+
+---
+
+## Composition Rules
+
+### Advisory Mode (implementation, fast-implementation)
+
+Used when subagents provide recommendations alongside the primary developer agent.
+
+1. Orchestrator reads `## Subagent Signals` from feasibility.md
+2. Applies mapping rules to select subagent(s)
+3. Spawns `developer.md` (primary, foreground)
+4. Spawns selected subagent(s) in **background** with advisory prompt:
+
+```
+You are being invoked as an advisory specialist during implementation.
+Review the design and implementation constraints below. Provide
+language/domain-specific recommendations focusing on:
+- Idiomatic patterns and conventions for [language/framework]
+- Common pitfalls and anti-patterns to avoid
+- Performance patterns specific to this stack
+- Framework-specific best practices
+
+Return findings as a structured list under these headings:
+## Recommendations, ## Pitfalls to Avoid, ## Patterns to Follow
+
+Design context:
+[design slice]
+
+Files in scope:
+[file list]
+```
+
+5. Developer.md proceeds immediately — **not blocked** by subagent
+6. When subagent returns, orchestrator appends findings to `implementation.md` under `## Specialist Advisory`
+7. If subagent findings conflict with developer output, orchestrator notes the conflict but does NOT automatically re-implement — logs it for code-review consideration
+
+### Parallel Review Mode (code-review)
+
+Used when specialist reviewers run alongside the main code review.
+
+1. Orchestrator reads `## Subagent Signals` from feasibility.md
+2. Selects 0-2 review-oriented subagents based on domain signals:
+   - Security-sensitive code → `security-auditor`
+   - Performance-sensitive code → `performance-engineer`
+   - Accessibility changes → `accessibility-tester`
+   - Infrastructure changes → `security-engineer`
+3. Spawns them in **background** simultaneously with main `/diff-review`
+4. Main code-review proceeds normally — specialist reviews do NOT block
+5. When specialist returns, findings appended to review artifact under `## Specialist Review Findings`
+6. If any specialist finding is severity `high` or `critical`, it is flagged in the main review verdict — but the main review verdict still controls the transition
+
+### Pre-Design Input Mode (design)
+
+Used when domain expertise should inform the design before panel review.
+
+1. Orchestrator reads `## Subagent Signals` from feasibility.md
+2. If a domain specialist is indicated with high confidence, spawn it **before** the design panel with a focused prompt:
+
+```
+Review the feasibility analysis and provide domain-specific input for
+the design. Focus on: architectural constraints, technology choices,
+integration patterns, and risks specific to [domain].
+
+Feasibility context:
+[feasibility.md content]
+```
+
+3. Specialist output is integrated into `design.md` under `## Domain Specialist Input` before panel review begins
+4. Panel reviewers see the specialist input alongside the design
+
+### Agent-to-Agent Delegation
+
+Core agents (`developer.md`, panel agents) can spawn subagents themselves when they encounter domain-specific complexity during their work.
+
+**Rules for agent-to-agent delegation:**
+
+1. The calling agent detects a need it cannot handle optimally (e.g., developer hits complex Rust lifetime issues, or encounters unfamiliar framework patterns)
+2. The calling agent reads `.claude/phases/subagent-selection.md` mapping tables to identify the right specialist
+3. The calling agent spawns the subagent in **background** with a focused, bounded prompt describing the specific problem
+4. The calling agent continues its work — does NOT block on the subagent
+5. When the subagent returns, the calling agent integrates findings into its own output
+6. The calling agent logs the delegation: `action=agent-delegate source=<calling-agent> target=<subagent> note="<specific problem>"`
+
+**Constraints on agent-to-agent delegation:**
+
+- Maximum 1 subagent spawn per calling agent per phase
+- Subagent must come from the mapping tables (no ad-hoc selection)
+- Calling agent must include the subagent's findings in its output (not silently discard)
+- If subagent contradicts the calling agent, both perspectives are reported to the orchestrator
+
+---
+
+## Fast Path vs Full Path
+
+### Fast path (`subagent-mode: minimal`)
+
+- Signal collection happens in feasibility (zero extra cost)
+- During fast-implementation: spawn **at most 1** language specialist
+  - Only if confidence is `high`
+  - Only if the language matches the primary language of changed files
+  - Runs in **background** (non-blocking)
+  - If fast-implementation finishes before specialist returns, **proceed without waiting**
+- No domain specialists on fast path
+- No review specialists on fast path (fast path has no separate code-review phase)
+- Developer.md can still use agent-to-agent delegation (1 spawn max)
+
+### Full path (`subagent-mode: full`)
+
+- Up to 2 subagents per phase (typically 1 language + 1 domain)
+- Implementation: language specialist + domain specialist (both background, advisory)
+- Code-review: up to 2 review specialists in parallel with main review
+- Design: up to 1 domain specialist as pre-design input (foreground, focused scope)
+- Developer.md can use agent-to-agent delegation (1 spawn max)
+
+---
+
+## Budget Constraints
+
+- Subagent spawns count against the iteration budget
+- Each subagent spawn adds estimated cost to `cost_used` in state.json
+- Model routing from subagent frontmatter determines cost tier (opus > sonnet > haiku)
+- **If `budget_remaining` < 3, skip all subagent auto-selection** — preserve budget for core work
+- Maximum 2 orchestrator-spawned subagents per phase invocation
+- Maximum 1 agent-to-agent delegation per calling agent per phase
+- Total subagent spawns tracked in `state.json.counters.subagent_spawns`
+
+---
+
+## Audit Logging
+
+Every auto-selected subagent must be logged in `audit.log`:
+
+```
+action=auto-select target=<subagent-path> phase=<phase> signals="<evidence>" confidence=<high|medium> mode=<advisory|review|input>
+action=agent-delegate source=<calling-agent> target=<subagent-path> note="<specific problem>"
+action=integrate-subagent target=<subagent-path> result=<integrated|conflict|skipped>
+action=skip-subagent phase=<phase> reason="<why not selected>"
+```
+
+The `skip-subagent` entry is logged only when signals existed but selection was suppressed (budget, confidence threshold, mode constraint).
+
+---
+
+## Override
+
+- Set `state.json.pipeline.subagent_auto_select` to `false` to disable all auto-selection
+- The user can also say "skip subagents" or "no subagents" during a `/work` session
+- Manual `/subagent invoke` always works regardless of this setting
+
+---
+
+## Conflict Resolution
+
+If a subagent finding contradicts the primary agent or orchestrator:
+
+1. Log the conflict in `audit.log`
+2. Include both perspectives in the phase artifact (under `## Specialist Advisory` or `## Specialist Review Findings`)
+3. The orchestrator or calling agent (not the subagent) decides which perspective to follow
+4. Record the resolution rationale in the artifact
+
+Subagents are advisory. They enhance quality but never override the primary workflow.

package/.claude/phases/test.md

@@ -0,0 +1,68 @@
+# Test
+
+This phase operates in two modes.
+
+## Mission
+
+- **Phase 1 (test stubs)**: Define the target test surface before implementation. Write stubs and placeholders for decisive checks.
+- **Phase 2 (execution)**: Run the narrowest decisive automated and manual checks after implementation. Feed failures back with precise evidence.
+
+## Persona
+
+Senior test engineer — values decisive evidence over coverage theater. Prefers deterministic, reproducible checks.
+
+## Procedure — Phase 1: Stub Generation
+
+1. Read `design.md`.
+2. Identify the behaviors that must be proven for correctness.
+3. Choose the narrowest useful test surfaces (unit, integration, contract, manual).
+4. Prioritize the most likely regression paths and highest-risk invariants.
+5. Write stub/scaffold test files that make the intended verification surface explicit.
+
+## Procedure — Phase 1.5: Adequacy Assessment
+
+After writing test stubs and before implementation begins, assess:
+
+1. **Acceptance criteria coverage**: what fraction of acceptance criteria have at least one test? (target: 100%)
+2. **Risk-weighted coverage**: are the top 3 risk items from design tested?
+3. **Edge case coverage**: are boundary conditions, error paths, and empty/null inputs addressed?
+4. **Regression coverage**: are the most likely regression paths tested?
+
+Score: `adequate` or `gaps-identified`. If `gaps-identified`, add missing stubs before proceeding.
+
+Record the assessment in `test-stubs.md` under an "Adequacy Assessment" section.
+
+## Procedure — Phase 2: Execution
+
+1. Invoke `/test-runner` to detect and execute the test suite. Scope to relevant test files when possible.
+2. Start with the narrowest decisive checks.
+3. Expand only when risk justifies additional coverage.
+4. Capture exact commands, exact failures, and confidence level.
+5. If validation is blocked by environment, say so explicitly.
+
+## Inputs
+
+- `.claude/.work/<id>/design.md`
+- `.claude/.work/<id>/implementation.md` (Phase 2 only)
+- Relevant source files and test files
+
+## Required Output
+
+**Phase 1**: Write `.claude/.work/<id>/test-stubs.md` following `.claude/templates/artifact-format.md`, with:
+
+- intended test files and behaviors each test should prove
+- highest-risk regression targets
+- what still cannot be tested yet
+
+**Phase 2**: Write `.claude/.work/<id>/test-results.md` with:
+
+- checks executed, result of each, confidence level
+- failures and likely cause
+- next action
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if no automated test path exists, define manual checks and document why automation was not feasible
+- avoid broad claims of confidence without evidence

package/.claude/phases/validation.md

@@ -0,0 +1,58 @@
+# Validation
+
+## Mission
+
+Run integrated validation and classify the outcome as approved, rejected, or blocked.
+
+## Persona
+
+Release gatekeeper — trusts execution evidence over reasoning, classifies failures precisely.
+
+## Procedure
+
+0. If on fast path (`state.json.pipeline.fast_path_eligible == true`):
+   - Check that `implementation.md` contains test evidence (command + output + result).
+   - If the change is behavioral (not documentation-only) and no test evidence exists, classify as `failed` with reason: "missing test evidence for behavioral change".
+
+1. Run the strongest available integrated checks:
+   - Invoke `/test-runner` for test execution
+   - Invoke `/lint` for lint and format checks
+   - Run build and typecheck commands directly
+2. Capture exact commands and decisive outputs.
+3. Classify the result:
+   - `approved`: all checks pass
+   - `failed`: code defects found
+   - `blocked`: environment or infrastructure issue
+4. If blocked, identify the blocking layer (local env, missing secret, flaky infra, unsupported path).
+5. Recommend whether to return to implementation or escalate.
+6. Retry blocked validation only within the configured budget.
+
+## Reflection on Failure
+
+When classification is `failed`, append a structured entry to `.claude/.work/<id>/reflection-log.md`:
+
+- **What failed**: which checks failed and exact output
+- **Root cause**: hypothesis for why the failure occurred
+- **Strategy change**: what the implementation should change to address the failure
+
+## Inputs
+
+- `.claude/.work/<id>/implementation.md`
+- `.claude/.work/<id>/permissions-changes.md` (if exists)
+- Repository build/test/lint configuration
+
+## Required Output
+
+Write `.claude/.work/<id>/validation-results.md` following `.claude/templates/artifact-format.md`, with:
+
+- commands run and observed output summary
+- classification: `approved`, `failed`, or `blocked`
+- confidence, retry count
+- recommended next state
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if execution evidence is weak, say so
+- if a failure is flaky, explain why you believe it is flaky

package/.claude/phases/verification.md

@@ -0,0 +1,45 @@
+# Verification
+
+## Mission
+
+Run the seven-check artifact scan and determine whether the pipeline can safely proceed from design into implementation preparation.
+
+## Persona
+
+Release-quality checker for planning artifacts — assumes planning debt becomes implementation debt.
+
+## Procedure
+
+Execute the seven-check scan mechanically:
+
+1. `state.json` is consistent with the intended next state
+2. `feasibility.md` exists and is coherent
+3. `design.md` exists and maps to real repository files
+4. acceptance criteria are testable
+5. planned implementation slices are bounded
+6. major risks are named
+7. the validation strategy is credible
+
+Treat missing evidence and contradictory planning as real failures. Classify each check as pass, fail, or blocked.
+
+## Inputs
+
+- `.claude/.work/<id>/state.json`
+- `.claude/.work/<id>/feasibility.md`
+- `.claude/.work/<id>/design.md`
+
+## Required Output
+
+Write `.claude/.work/<id>/verification-results.md` following `.claude/templates/artifact-format.md`, with:
+
+- each of the seven checks with pass/fail/blocked status
+- structural findings
+- required repair action (if any)
+- recommended next state
+
+Apply `.claude/templates/evidence-standard.md` throughout.
+
+## Failure Protocol
+
+- if planning artifacts are contradictory, return to design
+- if artifacts are missing entirely, mark as blocked

package/.claude/references/frontend-aesthetics.md

@@ -0,0 +1,91 @@
+# Frontend Aesthetics Reference
+
+Source: [Anthropic Claude Cookbooks — Prompting for Frontend Aesthetics](https://github.com/anthropics/claude-cookbooks/blob/main/coding/prompting_for_frontend_aesthetics.ipynb)
+
+This reference defines the aesthetic standards all frontend-generating agents must follow. The goal is to produce visually distinctive, polished frontends instead of generic "AI slop" designs.
+
+## Distilled Aesthetics Prompt
+
+All frontend agents must include this prompt context when generating UI code:
+
+```
+<frontend_aesthetics>
+You tend to converge toward generic, "on distribution" outputs. In frontend design, this creates what users call the "AI slop" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight. Focus on:
+
+Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.
+
+Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.
+
+Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.
+
+Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.
+
+Avoid generic AI-generated aesthetics:
+- Overused font families (Inter, Roboto, Arial, system fonts)
+- Cliche color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and component patterns
+- Cookie-cutter design that lacks context-specific character
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics.
+</frontend_aesthetics>
+```
+
+## Typography Guide
+
+### Never Use
+Inter, Roboto, Open Sans, Lato, Arial, default system fonts
+
+### Recommended Font Choices
+
+| Context | Fonts |
+|---------|-------|
+| Code / Technical | JetBrains Mono, Fira Code, Space Grotesk |
+| Editorial / Content | Playfair Display, Crimson Pro, Fraunces |
+| Startup / Modern | Clash Display, Satoshi, Cabinet Grotesk |
+| Distinctive / Unique | Bricolage Grotesque, Obviously, Newsreader |
+
+### Pairing Principle
+High contrast = interesting. Pair display + monospace, serif + geometric sans. Use weight extremes (100/200 vs 800/900), not timid mid-range differences (400 vs 600).
+
+## Color & Theme Guide
+
+- Commit to a cohesive aesthetic — don't mix conflicting styles
+- Use CSS variables for consistency across the design
+- Dominant colors with sharp accents outperform timid, evenly-distributed palettes
+- Draw inspiration from IDE themes (Dracula, Nord, Solarized, Tokyo Night) and cultural aesthetics (Solarpunk, Brutalism, Art Deco)
+- Avoid: purple gradients on white backgrounds (the most cliched AI-generated look)
+
+## Motion Guide
+
+- CSS-only animations for vanilla HTML projects
+- Motion library (Framer Motion) for React projects when available
+- Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) > scattered micro-interactions
+- Use `animation-delay` for staggered entrance effects
+- Keep animations purposeful — every animation should communicate something
+
+## Background Guide
+
+- Create atmosphere and depth — never default to flat solid colors
+- Layer CSS gradients for richness
+- Use geometric patterns or noise textures for character
+- Add contextual effects that match the overall aesthetic
+- Consider subtle animated backgrounds for hero sections
+
+## Theme Examples
+
+### Solarpunk
+Warm, optimistic palettes (greens, golds, earth tones). Organic shapes mixed with technical elements. Nature-inspired patterns. Bright, hopeful atmosphere. Retro-futuristic typography.
+
+### Brutalist
+Raw, honest materials. High contrast. Monospace typography. Minimal decoration. Strong grid systems. Intentionally rough edges.
+
+### Art Deco
+Geometric patterns. Gold and jewel tones. Elegant serif fonts. Symmetry and luxury. Ornamental borders.
+
+## Application Rules
+
+1. Always load distinctive fonts from Google Fonts (or equivalent CDN)
+2. State font and theme choices before writing code
+3. Use CSS variables for all colors, spacing, and typography values
+4. Vary between light and dark themes across different projects
+5. Each project should have a unique visual identity — no two should look alike

package/.claude/references/github.md

@@ -0,0 +1,73 @@
+# GitHub
+
+Authoritative workflow guidance for all git and GitHub operations in this pipeline.
+
+## Source Priority
+
+- Git core behavior: official Git docs at `git-scm.com/docs`
+- GitHub repository and PR workflow: `docs.github.com`
+- GitHub CLI behavior: `cli.github.com/manual`
+
+## Core Facts
+
+- `git pull` fetches and then integrates remote changes by merge or rebase depending on options and configuration.
+- a non-fast-forward push is rejected to avoid losing history; GitHub Docs recommend fetching and merging or using `git pull` before pushing again.
+- `gh pr create` prints the PR URL on success.
+- `gh pr create --dry-run` is not side-effect free and may still push git changes.
+- first push of a new branch commonly uses `git push --set-upstream origin <branch>`.
+
+## Preconditions
+
+Before git workflow actions:
+
+- relevant tests have passed or gaps are documented
+- the worktree has been inspected for unrelated changes
+- you know whether the repository is a direct clone or a fork
+- you know the intended base branch
+
+## Operational Guidance
+
+- confirm branch, remotes, and worktree status before git or GitHub actions
+- do not invent PR URLs
+- do not use force push casually; prefer `--force-with-lease` over raw `--force`
+- if auth, permissions, or branch protection prevent an action, record the exact blocker
+- prefer explicit flags with `gh pr create` for deterministic behavior
+
+## Common Workflows
+
+For step-by-step branch, sync, and conflict procedures, see `.claude/agents/git-ops.md`. This reference provides the authoritative facts those procedures rely on.
+
+### Create Pull Request
+
+```bash
+gh pr create --base <base-branch> --title "<title>" --body "<body>"
+```
+
+## Fetch, Pull, Merge, Rebase
+
+- `git fetch <remote>` retrieves remote updates without modifying the working branch
+- `git pull` fetches and integrates; local work must be committed first
+- `git merge <remote>/<branch>` integrates remote-tracking changes, preserving history
+- `git rebase` replays local commits onto a new base; do not rebase shared history
+
+## Conflict Resolution
+
+Inspect markers, preserve upstream fixes, abort when unsafe. See `.claude/agents/git-ops.md` Conflict Rules for procedure.
+
+## Fork and Upstream Sync
+
+Verify remotes: `origin` = fork, `upstream` = original. Add `upstream` if missing. See `.claude/agents/git-ops.md` for sync procedure.
+
+## Decision Heuristics
+
+- prefer merge when preserving shared history is safer than rewriting
+- prefer rebase when local unshared commits need linear history
+- prefer draft PRs when work is visible but not merge-ready
+- keep commits atomic
+- prefer non-interactive, explicit, reversible commands
+
+## Required Recordkeeping
+
+- record the actual PR URL in `.claude/.work/<id>/pr-link.txt`
+- record important git workflow actions in `.claude/.work/<id>/progress.md`
+- record blockers and failed workflow attempts in `.claude/.work/<id>/audit.log`

package/.claude/templates/artifact-format.md

@@ -0,0 +1,33 @@
+# Artifact Format
+
+Cite this template when writing phase artifacts to ensure consistent structure.
+
+## Standard Structure
+
+```markdown
+# <Phase Name>
+
+## Inputs
+- what was read or received
+
+## Findings
+- observations, analysis, and evidence-backed conclusions
+- follow `.claude/templates/evidence-standard.md` for evidence quality
+
+## Verdict
+- clear decision: approved, rejected, blocked, simple, complex, etc.
+- confidence level when applicable
+
+## Evidence Basis
+- specific files, commands, outputs, or documentation that support the verdict
+
+## Recommended Next State
+- the state transition this artifact supports
+- any conditions or caveats
+```
+
+## Rules
+
+- every artifact must have a verdict — commentary without a decision is not sufficient
+- evidence basis must reference concrete sources, not general reasoning
+- recommended next state must be a valid transition per the state machine in CLAUDE.md