chore(docs): improve docs

krokoko · krokoko · commit 5bd093414923 · 2026-04-08T21:33:01.000-05:00
diff --git a/.cursor/rules/agent-runtime.mdc b/.cursor/rules/agent-runtime.mdc
@@ -0,0 +1,13 @@
+---
+description: Python agent runtime in isolated compute
+globs: agent/**/*.py
+alwaysApply: false
+---
+
+# Agent runtime (`agent/`)
+
+- **`entrypoint.py`** is the main task loop; prompts live under **`agent/prompts/`** with **`system_prompt.py`** for shared behavior.
+- Follow **`agent/README.md`** for GitHub PAT scopes, env vars, and local **`./agent/run.sh`** usage.
+- Use **`mise run quality`** in **`agent/`** (or root **`mise run build`**, which runs agent quality before CDK) after substantive changes.
+- Do not embed secrets; the stack supplies credentials via Secrets Manager / env as documented.
+- Prefer **`ruff`** / existing patterns; see **`pyproject.toml`** for **`ruff`** and **`pytest`** configuration.
diff --git a/.cursor/rules/cdk-handlers.mdc b/.cursor/rules/cdk-handlers.mdc
@@ -0,0 +1,13 @@
+---
+description: CDK Lambda handlers and shared task pipeline conventions
+globs: cdk/src/handlers/**/*.ts
+alwaysApply: false
+---
+
+# CDK handlers
+
+- Prefer extending existing helpers in `cdk/src/handlers/shared/` (orchestration, validation, preflight) over duplicating logic.
+- When changing API shapes, edit **`cdk/src/handlers/shared/types.ts`** and mirror the same definitions in **`cli/src/types.ts`**.
+- Add or update Jest tests under **`cdk/test/handlers/`** or **`cdk/test/handlers/shared/`** next to the behavior you change (see **AGENTS.md** for a file map).
+- Use **`mise //cdk:test`** and **`mise //cdk:compile`** from the repo root instead of ad-hoc `jest` / `tsc` in the wrong directory.
+- Task lifecycle and admission behavior are described in **`docs/design/ORCHESTRATOR.md`**.
diff --git a/.cursor/rules/cli-package.mdc b/.cursor/rules/cli-package.mdc
@@ -0,0 +1,13 @@
+---
+description: bgagent CLI package conventions
+globs: cli/src/**/*.ts
+alwaysApply: false
+---
+
+# CLI (`@backgroundagent/cli`)
+
+- One command per file under **`cli/src/commands/`**; wire flags and options consistently with existing commands.
+- **`cli/src/types.ts`** must stay aligned with **`cdk/src/handlers/shared/types.ts`** when the REST API changes.
+- Console output is intentional: **`no-console`** is disabled for CLI sources.
+- The API base URL from deployment already includes the stage (e.g. **`/v1/`**); append only resource paths in **`api-client.ts`**.
+- Run **`mise //cli:build`** or **`cd cli && mise run test`** to verify changes.
diff --git a/.cursor/rules/docs-sources.mdc b/.cursor/rules/docs-sources.mdc
@@ -0,0 +1,11 @@
+---
+description: Authoritative docs live under guides/ and design/; Starlight is generated
+globs: docs/guides/**/*.md,docs/design/**/*.md
+alwaysApply: false
+---
+
+# Documentation sources
+
+- Edit **`docs/guides/`** and **`docs/design/`** (and root **`CONTRIBUTING.md`** when it affects the site). Do **not** hand-edit **`docs/src/content/docs/`** — that tree is produced by **`docs/scripts/sync-starlight.mjs`**.
+- After changing guides or design Markdown, run **`mise //docs:sync`** or **`mise //docs:build`** from the repo root.
+- **`AGENTS.md`** is the root entry for contributors and coding agents; keep it in sync conceptually when you change cross-cutting dev workflows.
diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml
@@ -9,6 +9,20 @@ body:
     attributes:
       value: |
         Thanks for helping improve the documentation. Relevant docs live in `docs/guides/`, `docs/design/`, and the repo README.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Doc area
+      description: What kind of documentation is affected?
+      options:
+        - User guide (`docs/guides/USER_GUIDE.md` or synced site)
+        - Developer guide (`docs/guides/DEVELOPER_GUIDE.md` or synced site)
+        - Design / architecture (`docs/design/`)
+        - Roadmap or prompts (`docs/guides/`)
+        - README / root docs
+        - Other
+    validations:
+      required: true
   - type: textarea
     id: description
     attributes:
diff --git a/.github/ISSUE_TEMPLATE/rfc.yml b/.github/ISSUE_TEMPLATE/rfc.yml
@@ -9,6 +9,21 @@ body:
     attributes:
       value: |
         Use this template for significant feature or design proposals. Please add as much detail as possible. See the [ROADMAP](https://github.com/krokoko/bgagent/blob/main/docs/guides/ROADMAP.md) and [design docs](https://github.com/krokoko/bgagent/tree/main/docs/design) for existing direction; your RFC should align or explain divergence.
+  - type: dropdown
+    id: area
+    attributes:
+      label: Primary area
+      description: Which part of the repo does this RFC mainly affect?
+      options:
+        - CDK / infrastructure
+        - Agent (Python runtime)
+        - CLI (bgagent)
+        - API or orchestration
+        - Documentation
+        - Tooling / CI
+        - Cross-cutting / multiple
+    validations:
+      required: true
   - type: input
     id: relation
     attributes:
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
diff --git a/AGENTS.md b/AGENTS.md
@@ -8,7 +8,40 @@ You are an **AWS CDK (Cloud Development Kit) and TypeScript** expert. This proje
 
 ## Project knowledge
 
-To get started and understand the developer flow, follow the [Developer guide](./docs/guides/DEVELOPER_GUIDE.md). For architecture and design, see [docs/design/](./docs/design/ARCHITECTURE.md).
+To get started and understand the developer flow, follow the [Developer guide](./docs/guides/DEVELOPER_GUIDE.md). For architecture and design, see [docs/design/](./docs/design/ARCHITECTURE.md). Task lifecycle and handler contracts are summarized in [Orchestrator design](./docs/design/ORCHESTRATOR.md) (including **API and agent contracts**).
+
+### Where to make changes
+
+Use this routing before editing so the right package and tests get updated:
+
+| Change | Primary location | Also update |
+|--------|------------------|-------------|
+| REST API, Lambdas, task validation, orchestration | `cdk/src/handlers/`, `cdk/src/stacks/`, `cdk/src/constructs/` | Matching tests under `cdk/test/` |
+| Shared API request/response shapes | `cdk/src/handlers/shared/types.ts` | **`cli/src/types.ts`** (must stay in sync) |
+| `bgagent` CLI commands and HTTP client | `cli/src/`, `cli/test/` | `cli/src/types.ts` if API types change |
+| Agent runtime (clone, tools, prompts, container) | `agent/` (`entrypoint.py`, `prompts/`, `Dockerfile`, etc.) | `agent/tests/`, `agent/README.md` for env/PAT |
+| User-facing or design prose | `docs/guides/`, `docs/design/` | Run **`mise //docs:sync`** or **`mise //docs:build`** (do not edit `docs/src/content/docs/` by hand) |
+| Monorepo tasks, CI glue | Root `mise.toml`, `scripts/`, `.github/workflows/` | — |
+
+### CDK handler tests (quick map)
+
+Colocated tests under `cdk/test/handlers/shared/` cover most shared logic:
+
+- `validation.test.ts` — request validation
+- `preflight.test.ts` — preflight / admission checks
+- `create-task-core.test.ts` — task creation core path
+- `context-hydration.test.ts` — prompt / context assembly
+- `repo-config.test.ts`, `memory.test.ts`, `gateway.test.ts`, `response.test.ts`, `prompt-version.test.ts` — respective modules
+
+Handler entry tests: `cdk/test/handlers/orchestrate-task.test.ts`, `create-task.test.ts`, `webhook-create-task.test.ts`. Construct wiring: `cdk/test/constructs/task-orchestrator.test.ts`, `task-api.test.ts`.
+
+### Common mistakes
+
+- Editing **`docs/src/content/docs/`** instead of **`docs/guides/`** or **`docs/design/`** — content is generated; sync from sources.
+- Changing **`cdk/.../types.ts`** without updating **`cli/src/types.ts`** — CLI and API drift.
+- Running raw **`jest`/`tsc`/`cdk`** from muscle memory — prefer **`mise //cdk:test`**, **`mise //cdk:compile`**, **`mise //cdk:synth`** (see [Commands you can use](#commands-you-can-use)).
+- **`MISE_EXPERIMENTAL=1`** — required for namespaced tasks like **`mise //cdk:build`** (see [CONTRIBUTING.md](./CONTRIBUTING.md)).
+- **`mise run build`** runs **`//agent:quality`** before CDK — the deployed image bundles **`agent/`**; agent changes belong in that tree.
 
 ### Tech stack
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -22,6 +22,8 @@ When filing an issue, please check [existing open](https://github.com/aws-sample
 
 ### Pull Request Checklist
 
+When planning edits, use **[AGENTS.md](./AGENTS.md)** at the repo root for **where to change code** (CDK vs CLI vs agent vs docs), **which tests to extend**, and **common pitfalls** (generated docs, mirrored API types, `mise` tasks).
+
 * [ ] Testing
   - Unit test added (prefer not to modify an existing test, otherwise, it's probably a breaking change)
   - Integration test added (if adding a new pattern or making a significant update to an existing pattern)
diff --git a/cdk/src/handlers/shared/create-task-core.ts b/cdk/src/handlers/shared/create-task-core.ts
@@ -17,6 +17,9 @@
  *  SOFTWARE.
  */
 
+// HTTP create-task path: validation, persistence, orchestrator invoke. Related: orchestrator.ts, preflight.ts.
+// Tests: cdk/test/handlers/shared/create-task-core.test.ts, cdk/test/handlers/create-task.test.ts
+
 import { BedrockRuntimeClient, ApplyGuardrailCommand } from '@aws-sdk/client-bedrock-runtime';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import { InvokeCommand, LambdaClient } from '@aws-sdk/client-lambda';
diff --git a/cdk/src/handlers/shared/orchestrator.ts b/cdk/src/handlers/shared/orchestrator.ts
@@ -17,6 +17,9 @@
  *  SOFTWARE.
  */
 
+// Task lifecycle engine: state transitions, runtime invoke, finalization. Design: docs/design/ORCHESTRATOR.md
+// Tests: cdk/test/handlers/orchestrate-task.test.ts, cdk/test/constructs/task-orchestrator.test.ts
+
 import { randomUUID } from 'crypto';
 import { InvokeAgentRuntimeCommand, BedrockAgentCoreClient } from '@aws-sdk/client-bedrock-agentcore';
 import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
diff --git a/cdk/src/handlers/shared/preflight.ts b/cdk/src/handlers/shared/preflight.ts
@@ -17,6 +17,9 @@
  *  SOFTWARE.
  */
 
+// Admission / pre-invoke checks before orchestration. See docs/design/ORCHESTRATOR.md (admission control).
+// Tests: cdk/test/handlers/shared/preflight.test.ts
+
 import { resolveGitHubToken } from './context-hydration';
 import { logger } from './logger';
 import type { BlueprintConfig } from './repo-config';
diff --git a/docs/design/ORCHESTRATOR.md b/docs/design/ORCHESTRATOR.md
@@ -14,6 +14,19 @@ The orchestrator does **not** run the agent. The agent runs inside an isolated c
 - **Most important sections for readers:** Responsibilities, State machine, Admission control, and Cancellation.
 - **Scope:** orchestrator behavior only; API surface and security policy are defined in their dedicated docs.
 
+## API and agent contracts
+
+These boundaries matter whenever you change task submission, the CLI, or the runtime container.
+
+| Concern | Canonical location | Notes |
+|---------|-------------------|--------|
+| REST request/response types | `cdk/src/handlers/shared/types.ts` | **Mirror** in `cli/src/types.ts` for `bgagent` — keep them aligned on every API change. |
+| HTTP handlers & orchestration code | `cdk/src/handlers/` (e.g. shared `orchestrator.ts`, `create-task-core.ts`, `preflight.ts`) | Colocated Jest tests under `cdk/test/handlers/` and `cdk/test/handlers/shared/`. |
+| Agent runtime behavior | `agent/` (`entrypoint.py`, `prompts/`, `system_prompt.py`, Dockerfile) | Consumes task payload and environment set by CDK/Lambda; see `agent/README.md` for PAT, tools, and local run. |
+| User-facing API documentation | `docs/guides/USER_GUIDE.md` (and synced site) | Regenerate Starlight content with `mise //docs:sync` after guide edits. |
+
+The orchestrator document describes **behavior** (state machine, admission, cancellation). The TypeScript `types.ts` files are the **schema** the API and CLI share; the agent implements the **work** inside compute.
+
 **Relationship to blueprints.** The orchestrator is a **framework** that enforces platform invariants — the task state machine, event emission, concurrency management, and cancellation handling — and delegates variable work to **blueprint-defined step implementations**. A blueprint defines which steps run, in what order, and how each step is implemented (built-in strategy, Lambda-backed custom step, or custom sequence). The default blueprint is defined in this document (Section 4). Per-repo customization (see [REPO_ONBOARDING.md](./REPO_ONBOARDING.md)) changes the steps the orchestrator executes, not the framework guarantees it enforces. The orchestrator wraps every step with state transitions, event emission, and cancellation checks — regardless of whether the step is a built-in or a custom Lambda.
 
 ### Iteration 1 vs. target state
diff --git a/docs/guides/DEVELOPER_GUIDE.md b/docs/guides/DEVELOPER_GUIDE.md
@@ -11,6 +11,20 @@ The repository is organized around four main pieces:
 - **Documentation site** under `docs/` — source guides/design docs plus the generated Astro/Starlight documentation site.
 - **CLI package** under `cli/` — the `bgagent` command-line client used to authenticate, submit tasks, and inspect task status/events.
 
+## Where to make changes
+
+Before editing, decide which part of the monorepo owns the behavior. This keeps API types, CLI, and docs in sync.
+
+| Area | Paths | Notes |
+|------|--------|--------|
+| API & Lambdas | `cdk/src/handlers/`, `cdk/src/stacks/`, `cdk/src/constructs/` | Extend `cdk/test/` for the same feature. |
+| API types | `cdk/src/handlers/shared/types.ts` and **`cli/src/types.ts`** | Update both when request/response shapes change. |
+| CLI | `cli/src/`, `cli/test/` | — |
+| Agent runtime | `agent/` | Bundled into the image CDK deploys; run `mise run quality` in `agent/` or root build. |
+| Docs (source) | `docs/guides/`, `docs/design/` | After edits, run **`mise //docs:sync`** or **`mise //docs:build`**. Do not edit `docs/src/content/docs/` directly. |
+
+For a concise duplicate of this table, common pitfalls, and a CDK test file map, see **[AGENTS.md](../../AGENTS.md)** at the repo root (oriented toward automation-assisted contributors).
+
 ## Repository preparation
 
 The CDK stack ships with a **sample onboarded repository** (`krokoko/agent-plugins` in `cdk/src/stacks/agent.ts`) so the project deploys and CDK tests run cleanly out of the box. That value is for **default wiring only**: a real agent run **pushes branches and opens pull requests** with your GitHub PAT, so the onboarded repo must be one your token can **clone, push to, and open PRs on**. Most people do **not** have that access to the upstream repo.
diff --git a/docs/src/content/docs/design/Orchestrator.md b/docs/src/content/docs/design/Orchestrator.md
diff --git a/docs/src/content/docs/developer-guide/Contributing.md b/docs/src/content/docs/developer-guide/Contributing.md
diff --git a/docs/src/content/docs/developer-guide/Where-to-make-changes.md b/docs/src/content/docs/developer-guide/Where-to-make-changes.md
@@ -0,0 +1,15 @@
+---
+title: Where to make changes
+---
+
+Before editing, decide which part of the monorepo owns the behavior. This keeps API types, CLI, and docs in sync.
+
+| Area | Paths | Notes |
+|------|--------|--------|
+| API & Lambdas | `cdk/src/handlers/`, `cdk/src/stacks/`, `cdk/src/constructs/` | Extend `cdk/test/` for the same feature. |
+| API types | `cdk/src/handlers/shared/types.ts` and **`cli/src/types.ts`** | Update both when request/response shapes change. |
+| CLI | `cli/src/`, `cli/test/` | — |
+| Agent runtime | `agent/` | Bundled into the image CDK deploys; run `mise run quality` in `agent/` or root build. |
+| Docs (source) | `docs/guides/`, `docs/design/` | After edits, run **`mise //docs:sync`** or **`mise //docs:build`**. Do not edit `docs/src/content/docs/` directly. |
+
+For a concise duplicate of this table, common pitfalls, and a CDK test file map, see **[AGENTS.md](/design/agents)** at the repo root (oriented toward automation-assisted contributors).
