Grace AGENTS.md

Agent Instructions

Other AGENTS.md files exist in subdirectories, refer to them for more specific context.

Agent Quickstart (Local)

Prerequisites:

• PowerShell 7.x
• .NET 10 SDK
• Docker Desktop (required for -Full)

Commands:

• pwsh ./scripts/bootstrap.ps1
• Run the smallest meaningful focused proof for the changed slice.

Use pwsh ./scripts/validate.ps1 -Fast as an optional broad local preflight and -Full for local integration reproduction or diagnosis. GitHub Validate is the required broad gate for the current pull-request revision. Optional: pwsh ./scripts/install-githooks.ps1 adds a lightweight pre-commit staged-diff check; focused tests and formatting remain explicit responsibilities.

More context:

• src/AGENTS.md
• skills/grace/SKILL.md for Agent Skills-compatible clients; use it as the portable Grace context router after reading repo-local instructions.
• src/docs/ASPIRE_SETUP.md
• src/docs/ENVIRONMENT.md

Issue Tracking

• Use GitHub issues and pull requests as the active coordination surface for implementation work.
• For non-trivial work, follow docs/Development process.md: create or confirm a GitHub issue, declare owned paths, create an issue-owned branch/worktree, validate in focused slices, commit after each completed slice, and record docsimpact and skipped validation.
• For multi-step implementation plans, create an epic parent issue, but initially create only the earliest tracer and prerequisites proven necessary by current evidence. Use native GitHub parent relationships and a compact dependency map for created work. Do not pre-create a broad horizontal issue forest. Re-plan and create later child issues after the tracer runs. Use the concrete addSubIssue GraphQL workflow in docs/Development process.md for each created child.
• When planning a feature or epic, and when creating issue or pull request bodies, include why the change matters for Grace and its users. Use that purpose to help implementation agents make better local decisions when the plan leaves a gap or an acceptance criterion is ambiguous.
• When creating the epic and child issues from PowerShell, avoid one giant inline script that embeds every issue body.
• For large issue batches, go directly to a short-lived generator script checked into the worktree or written in a temp directory, run that script to emit one temporary Markdown body per issue, lint those files, then call gh issue create --body-file <path> for each issue. Do not paste large scripts through an interactive shell or pass them as a single pwsh -Command string; that wastes time, floods the transcript, and can hit Windows command-length limits. After issue creation, patch the epic body with the real child issue numbers and create the native relationships with GraphQL addSubIssue.
• Keep epics as durable product and planning records, not long-running agent conversations. Use fresh epic-checkpoint sessions before the first child, after each merged child, and at epic closure. Select each child's delivery mode explicitly. Default to a mainline slice from current origin/main when the child is independently correct and safe or inert until consumed. Use an epic integration branch only when the owner approves a real composition need, CI coverage, refresh policy, delivery-delta review, and final epic-to-main release candidate. Do not create an epic branch merely because an issue has an epic parent.
• Use one checkpoint agent by default; at most two read-only scouts may answer concrete independent questions with explicit fork_turns = "none". Checkpoints never spawn implementation workers.
• Every pull request must link its related GitHub issue in the PR body. When a PR targets the default branch and should close an issue, use one of GitHub's supported closing keywords: close, closes, closed, fix, fixes, fixed, resolve, resolves, or resolved. Use docs/Development process.md for default-branch versus epic-branch wording so links stay traceable without relying on epic-branch auto-close behavior.