aw-spec-cli 0.1.0 → 0.1.2

package/assets/.aw-spec/templates/spec-template.md

@@ -0,0 +1,131 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`
+
+**Created**: [DATE]
+
+**Status**: Draft
+
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+## Assumptions
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right assumptions based on reasonable defaults
+  chosen when the feature description did not specify certain details.
+-->
+
+- [Assumption about target users, e.g., "Users have stable internet connectivity"]
+- [Assumption about scope boundaries, e.g., "Mobile support is out of scope for v1"]
+- [Assumption about data/environment, e.g., "Existing authentication system will be reused"]
+- [Dependency on existing system/service, e.g., "Requires access to the existing user profile API"]

package/assets/.aw-spec/templates/tasks-template.md

@@ -0,0 +1,252 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `specs/[Aggregate]/[Feature]/`
+
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!--
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+
+  The /aw-spec-tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

package/assets/.aw-spec/workflows/aw-spec/workflow.yml

@@ -0,0 +1,77 @@
+schema_version: "1.0"
+workflow:
+  id: "aw-spec"
+  name: "Full SDD Cycle"
+  version: "1.0.0"
+  author: "GitHub"
+  description: "Runs specify → plan → tasks → implement with review gates"
+
+requires:
+  # 0.8.5 is the first release with engine-side resolution of the
+  # ``integration: "auto"`` default. Older versions would treat "auto"
+  # as a literal integration key and fail at dispatch.
+  aw-spec_version: ">=0.8.5"
+  integrations:
+    # The four commands below (specify, plan, tasks, implement) are core
+    # aw-spec commands provided by every integration. The list here is an
+    # advisory, non-exhaustive compatibility hint following the documented
+    # ``any: [...]`` schema -- it is NOT a closed set. The workflow runs
+    # against any integration the project was initialized with, including
+    # ones not listed below, as long as that integration provides the four
+    # core commands referenced in ``steps``.
+    any:
+      - "claude"
+      - "copilot"
+      - "gemini"
+      - "opencode"
+
+inputs:
+  spec:
+    type: string
+    required: true
+    prompt: "Describe what you want to build"
+  integration:
+    type: string
+    default: "auto"
+    prompt: "Integration to use (e.g. claude, copilot, gemini; 'auto' uses the project's initialized integration)"
+  scope:
+    type: string
+    default: "full"
+    enum: ["full", "backend-only", "frontend-only"]
+
+steps:
+  - id: specify
+    command: aw-spec.aw-spec
+    integration: "{{ inputs.integration }}"
+    input:
+      args: "{{ inputs.spec }}"
+
+  - id: review-spec
+    type: gate
+    message: "Review the generated spec before planning."
+    options: [approve, reject]
+    on_reject: abort
+
+  - id: plan
+    command: aw-spec.plan
+    integration: "{{ inputs.integration }}"
+    input:
+      args: "{{ inputs.spec }}"
+
+  - id: review-plan
+    type: gate
+    message: "Review the plan before generating tasks."
+    options: [approve, reject]
+    on_reject: abort
+
+  - id: tasks
+    command: aw-spec.tasks
+    integration: "{{ inputs.integration }}"
+    input:
+      args: "{{ inputs.spec }}"
+
+  - id: implement
+    command: aw-spec.implement
+    integration: "{{ inputs.integration }}"
+    input:
+      args: "{{ inputs.spec }}"

package/assets/.aw-spec/workflows/workflow-registry.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "workflows": {
+    "aw-spec": {
+      "name": "Full SDD Cycle",
+      "version": "1.0.0",
+      "description": "Runs specify \u2192 plan \u2192 tasks \u2192 implement with review gates",
+      "source": "bundled",
+      "installed_at": "2026-06-10T07:39:01.977990+00:00",
+      "updated_at": "2026-06-10T07:39:01.977996+00:00"
+    }
+  }
+}

package/assets/.claude/skills/aw-spec-addcomponent/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: "aw-spec-addcomponent"
+description: "Add an opt-in AppWeaver framework component to the project: pick a component from docs/components/, choose one or more implementations from its integration.md catalog, and wire the matching code in."
+argument-hint: "Optional component folder name to select directly (e.g. Email)"
+compatibility: "Requires aw-spec project structure with a docs/components/ directory whose subfolders each contain an integration.md runbook"
+metadata:
+  author: "github-aw-spec"
+  source: "local"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+The text the user typed after `/aw-spec-addcomponent` (if any) is an optional component folder name
+to select directly (e.g. `Email`). If it matches a folder under `docs/components/`, skip the
+component-selection prompt; otherwise fall through to interactive selection.
+
+## Purpose
+
+Add an **opt-in AppWeaver framework component** (Email, Jobs, QrGenerator, …) to the current
+project. Each component lives in its own folder under `docs/components/` and ships two
+agent-readable files: `README.md` (the contract) and `integration.md` (an **ordered agent
+runbook**). This command discovers the available components, lets the developer pick **one**, then
+lets them pick **one or more implementations** from that component's catalog, and finally executes
+the component's own `integration.md` runbook to add the required code.
+
+This command is the entry point; the per-component `integration.md` is the authority on *what code
+to add*. Always defer to the selected component's runbook for the actual edits, package versions,
+registration scaffold, and verification steps — do not invent integration steps from memory.
+
+## Outline
+
+1. **Discover candidate components.** List the immediate **subdirectories** of `docs/components/`
+   (directories only — ignore loose files such as `README.md`). This is the set of selectable
+   components.
+   - If `docs/components/` does not exist or has **no** subdirectories, report that no components
+     are available, point the user at `docs/components/README.md` for the expected layout, and
+     **stop** without changing anything.
+   - A component folder is only valid if it contains an `integration.md`. Skip (and note) any
+     subfolder missing one.
+
+2. **Direct argument (optional).** If the user passed an argument:
+   - If it exactly matches one of the discovered folder names, treat that as the chosen component
+     and skip to step 4.
+   - If it does not match any folder, note the mismatch, list the available names, and fall through
+     to the interactive selection in step 3.
+
+3. **Select the component (single-select).** Present the candidate components with the
+   `AskUserQuestion` tool (single-select, `multiSelect: false`). Use each folder name as the option
+   label and, if cheaply available, the one-line "Use when…" summary from
+   `docs/components/README.md` as the option description.
+   - If **more than 4** components exist, split across multiple `AskUserQuestion` questions/calls
+     (≤4 options per question).
+   - If **exactly one** component exists, ask a confirmation — *"Add component '<name>'?"* with
+     options **"Add '<name>'"** and **"Cancel"**.
+   - If the user cancels (or interactive questions cannot be asked and no valid argument was given),
+     **stop** without changing anything.
+
+4. **Load the component runbook.** Read `docs/components/<chosen>/integration.md` and, when it
+   references it, `docs/components/<chosen>/README.md`. Locate the **"Implementation catalog
+   (selection list)"** section — its table rows are the selectable implementations. Each row's
+   `Key` is the implementation identifier; capture each Key plus its human description for the
+   prompt.
+   - If `integration.md` is missing or has no implementation catalog, report that the component is
+     not integrable via this command and **stop**.
+
+5. **Select implementation(s) (multi-select).** Present the catalog rows with `AskUserQuestion`,
+   `multiSelect: true`. Use the `Key` as the option label and the row's "Implementation"/"Best for"
+   text as the description.
+   - If the catalog has a **single** row, tell the user it is the only available implementation and
+     ask them to confirm it (do not invent others).
+   - Honor any **grouping / selection rules** the component's `integration.md` states for reading
+     the answer (e.g. Jobs: pick exactly one Group A store, optionally one Group B status store).
+     If more rows exist than fit one prompt, split across multiple `AskUserQuestion` calls.
+
+6. **Empty selection → exit cleanly.** If the user submits with **nothing selected** (or cancels
+   the implementation prompt), do **not** modify the project. Report that no implementation was
+   chosen, name the component, and tell them they can re-run `/aw-spec-addcomponent` any time. Then
+   **stop**.
+
+7. **Add the code (one or more selected).** Execute the chosen component's `integration.md` runbook
+   **in order** for the selected implementation(s):
+   - Resolve the **host/startup project** the runbook targets — the single project that owns
+     `Program.cs` + the ASP.NET Core web SDK (`<App>.Service` for the Vertical Slice foundation,
+     `<App>.API` for the Modular Monolith foundation, or another name in a future template). **Find it
+     by locating `Program.cs`, not by assuming a fixed name.** These foundations have **no** separate
+     `…Application` / `…Infrastructure` project — package references, registration, and
+     `appsettings.json` all target this one project.
+   - Apply the runbook's **"Common steps"** once.
+   - Apply each selected implementation's **block** (package version in
+     `Directory.Packages.props`, `PackageReference` without `Version=`, registration line, config).
+   - Set `options.Provider` per the runbook (when multiple implementations are selected, follow the
+     runbook's rule for choosing the default/active provider — ask a single-select follow-up if it
+     requires one).
+   - Honor the cross-cutting rules in `docs/components/README.md` (R0.1–R0.5, incl. R0.2a): versions
+     only in `Directory.Packages.props`; register in the host/startup project resolved via `Program.cs`
+     (R0.2 — its `Extensions/InfrastructureServiceRegistration.cs`/`AddInfrastructure` if present,
+     else `Program.cs`); inject the abstraction; always set `options.Provider`; never commit secrets.
+   - **Register in both startup paths when they exist (R0.2a).** If the host project splits
+     registration into `AddInfrastructure` (`Extensions/InfrastructureServiceRegistration.cs`) **and**
+     `AddAspireInfrastructure` (`Extensions/AspireInfrastructureExtensions.cs`) — the
+     `if (isAspire) AddAspireInfrastructure(...) else AddInfrastructure(...)` switch in `Program.cs` —
+     add the component's registration to **both** methods, not just `AddInfrastructure`. The block is
+     the same in each, differing only in provider-specific calls (connection strings, `UseSqlite` vs
+     `UseNpgsql`) that must match that method's existing provider. Registering in only one leaves the
+     component missing whenever the app runs in the other mode.
+   - Run any optional usage/feature-slice and schema steps only if the runbook calls for them or the
+     user asks.
+
+8. **Verify and report.** Run the component runbook's **Verification** checklist (at minimum
+   `dotnet build`). Then report:
+   - the component added and which implementation key(s) were wired,
+   - the active provider,
+   - the files changed,
+   - any follow-ups the developer must do out-of-band (secrets, migrations, DDL).
+
+## Done When
+
+- [ ] A component was chosen, or nothing was changed (no components available, or the user
+      cancelled).
+- [ ] If implementations were selected, the component's `integration.md` runbook was executed for
+      each, the project builds, and the changes were reported.
+- [ ] If **no** implementation was selected, the project was left untouched and the user was told so.

package/assets/.claude/skills/aw-spec-agent-context-update/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: aw-spec-agent-context-update
+description: Refresh the managed AW-Spec section in the coding agent context file
+compatibility: Requires aw-spec project structure with .aw-spec/ directory
+metadata:
+  author: github-aw-spec
+  source: agent-context:commands/aw-spec.agent-context.update.md
+---
+
+# Update Coding Agent Context
+
+Refresh the managed AW-Spec section inside the active coding agent's context/instruction file (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`).
+
+## Behavior
+
+The script reads the agent-context extension config at
+`.aw-spec/extensions/agent-context/agent-context-config.yml` to discover:
+
+- `context_file` — the path of the coding agent context file to manage.
+- `context_markers.start` / `.end` — the delimiters surrounding the managed section. Defaults to `<!-- AW-SPEC START -->` and `<!-- AW-SPEC END -->` when the field is missing.
+
+It then creates, replaces, or appends the managed block so that the section points at the most recent plan path when one can be discovered (`specs/<feature>/plan.md`).
+
+If `context_file` is empty or the file cannot be located, the command reports nothing to do and exits successfully.
+
+## Execution
+
+- **Bash**: `.aw-spec/extensions/agent-context/scripts/bash/update-agent-context.sh [plan_path]`
+- **PowerShell**: `.aw-spec/extensions/agent-context/scripts/powershell/update-agent-context.ps1 [plan_path]`
+
+When `plan_path` is omitted, the script auto-detects the most recently modified `specs/*/plan.md`.