durable-context 1.0.0

package/template/.agents/skills/dive-into-plan/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: dive-into-plan
+description: Interrogate a settled initiative plan for gaps, distribute into per-concern docs, and promote accepted decisions into decisions/. Use ONLY when the human explicitly invokes it ("dive into the plan", "distribute the plan"). Do not trigger automatically.
+---
+
+# Dive Into Plan
+
+Second half of durable planning, after `plan-with-context`. Requires a settled `plan.md`.
+
+## Workflow
+
+1. Read initiative `README.md`, `plan.md`, and `context/project-profile.md` when it exists.
+2. **Interrogate** — ask pointed questions for surfaces the plan skipped (tests, e2e, IaC, CI/CD, config, ops, security, migration, reference impact). Record answers in `plan.md`; note deferred surfaces with reason.
+3. **Distribute** — move settled truth from `plan.md` into initiative files (see templates under `context/_templates/initiative/` for each file's role):
+   `spec.md`, `interface.md`, `architecture.md`, `testing.md`, `delivery.md`, `infrastructure.md`, `operations.md` (only when actionable), `backlog.md`, `release-doc-notes.md`. Mark N/A files explicitly.
+4. **Promote decisions** — for each accepted architecture/design choice: next `NNNN` in `decisions/` from `0000-template.md`, status Accepted, index row in `decisions/README.md`, origin link to initiative. Mark superseded decisions; never delete history.
+5. Update initiative `README.md` (status, decisions, implementation state).
+
+## Boundary
+
+Do not edit `reference/`. Capture future reference impact in `release-doc-notes.md` only.
+
+## Done when
+
+- Applicable surfaces grilled; answers in `plan.md`.
+- Settled truth not living only in `plan.md`.
+- Accepted decisions in repo-wide `decisions/` log.

package/template/.agents/skills/plan-with-context/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: plan-with-context
+description: Draft a durable plan in an initiative plan.md covering the full change surface. Use ONLY when the human explicitly invokes it ("plan with context", "plan with durable context", "durable plan"). Do not trigger for ordinary planning or small tasks.
+---
+
+# Plan With Context
+
+Invocation-only. Produces `plan.md` for a later `dive-into-plan` pass.
+
+## Workflow
+
+1. Read nearest `AGENTS.md` and `context/project-profile.md` when it exists.
+2. Find or create `context/initiatives/<slug>/` (copy `context/_templates/initiative/`). Update `README.md`, then work in `plan.md`. Skip initiatives for tiny fixes.
+3. Draft in `plan.md`: alignment, options, open questions. For each applicable surface, plan the work or mark N/A with reason:
+   - Application code · unit/integration tests · e2e · IaC · CI/CD · config/secrets (names only) · observability/rollback · security/data · reference impact
+4. Ground items in real repo tooling (profile or direct inspection). Do not guess.
+5. Iterate with the human until direction is settled. Do not distribute yet.
+
+## Handoff
+
+When settled, invoke `dive-into-plan`.
+
+## Done when
+
+- Initiative exists (or reason given why not).
+- `plan.md` covers every applicable surface.
+- Open questions visible; settled truth not frozen in `plan.md` alone.

package/template/AGENTS.md

@@ -0,0 +1,17 @@
+# Agent Guidance - PROJECT_NAME
+
+Area-specific `AGENTS.md` files layer on top of this one.
+
+<!-- durable-context:start -->
+## Durable Context
+
+Working context under [`context/`](context/); durable decisions under [`decisions/`](decisions/).
+Initiatives under [`context/initiatives/`](context/initiatives/) are disposable; promote accepted decisions to [`decisions/`](decisions/).
+
+Invocation-only skills — ask by name:
+
+- [`plan-with-context`](.agents/skills/plan-with-context/SKILL.md) — draft a plan in `plan.md`.
+- [`dive-into-plan`](.agents/skills/dive-into-plan/SKILL.md) — interrogate gaps, distribute into per-concern docs, promote to [`decisions/`](decisions/).
+
+[`context/project-profile.md`](context/project-profile.md) — repo-wide stack, commands, and test facts when populated.
+<!-- durable-context:end -->

package/template/context/README.md

@@ -0,0 +1,24 @@
+# context/
+
+Working bench for PROJECT_NAME — disposable planning context for work in progress.
+
+Persists elsewhere: [`../decisions/`](../decisions/) (durable log); `reference/` if reference-docs is installed.
+
+## Start Here
+
+- `initiatives/` — one folder per piece of work
+- `project-profile.md` — repo-wide stack, commands, tests, delivery (when populated)
+- `_templates/initiative/` — copy to start a new initiative
+
+## Flow
+
+```text
+plan-with-context  ->  initiatives/<slug>/plan.md
+dive-into-plan     ->  per-concern docs + ../decisions/
+```
+
+1. Copy `_templates/initiative/` to `initiatives/<slug>/`.
+2. Invoke `plan-with-context` to draft `plan.md`.
+3. When settled, invoke `dive-into-plan` to distribute and promote decisions.
+
+Settled truth must not live only in `plan.md`. Do not edit `reference/` from here — use `release-doc-notes.md` for future reference impact.

package/template/context/_templates/initiative/README.md

@@ -0,0 +1,29 @@
+# Initiative Title
+
+Status: Draft
+Primary area: TBD
+Started: YYYY-MM-DD
+
+## Summary
+
+
+
+## Touched Areas
+
+- 
+
+## Decisions
+
+Promote accepted decisions to repo-wide [`decisions/`](../../../decisions/).
+
+- None yet.
+
+## Open Questions
+
+- 
+
+## Implementation Status
+
+- Not started.
+
+Per-concern docs (`spec.md`, `architecture.md`, etc.) — see templates in this folder. Use `plan-with-context` then `dive-into-plan`.

package/template/context/_templates/initiative/architecture.md

@@ -0,0 +1,44 @@
+# Architecture
+
+## Context
+
+Describe the internal shape of the solution and the existing boundaries this
+initiative must respect.
+
+## Components
+
+| Component | Responsibility |
+| --- | --- |
+| TBD | TBD |
+
+## Flow
+
+Use Mermaid when the relationship between moving parts is easier to show than
+explain. Mermaid is valuable here because it stays readable as Markdown for
+agents while rendering as a visible diagram for humans.
+
+```mermaid
+flowchart LR
+    User[User or caller] -->|request| Entry[Entry point]
+    Entry -->|uses| Service[Service]
+    Service -->|reads/writes| Store[(Store)]
+```
+
+## Data And Contracts
+
+Describe entities, DTOs, events, messages, config, migrations, or external
+contracts affected by the initiative.
+
+## Boundaries
+
+Describe ownership boundaries, shared layers, external dependencies, and
+what this initiative must not take over.
+
+## Security And Compliance
+
+Capture authentication, authorization, data residency, audit, privacy,
+secret handling, and abuse cases.
+
+## Test Strategy
+
+List the tests or verification paths needed for confidence.

package/template/context/_templates/initiative/backlog.md

@@ -0,0 +1,23 @@
+# Backlog
+
+## Status Legend
+
+- `Todo`
+- `In Progress`
+- `Blocked`
+- `Done`
+- `Deferred`
+
+## Work Items
+
+| Status | Item | Area | Notes |
+| --- | --- | --- | --- |
+| Todo | Define first slice | TBD | TBD |
+
+## Deferred
+
+Use this section for work deferred within this initiative. If a deferred item
+is significant enough to track on its own, start a separate initiative for it
+under `context/initiatives/`.
+
+- None yet.

package/template/context/_templates/initiative/brief.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Initiative Brief</title>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      margin: 2rem;
+      line-height: 1.5;
+      color: #1f2933;
+      background: #ffffff;
+    }
+    main {
+      max-width: 960px;
+      margin: 0 auto;
+    }
+    h1, h2 {
+      line-height: 1.2;
+    }
+    table {
+      border-collapse: collapse;
+      width: 100%;
+    }
+    th, td {
+      border: 1px solid #d5dce3;
+      padding: 0.5rem;
+      text-align: left;
+      vertical-align: top;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Initiative Brief</h1>
+    <p>Use this optional page when a concise human-readable summary is useful.</p>
+
+    <h2>Outcome</h2>
+    <p>TBD</p>
+
+    <h2>Scope</h2>
+    <table>
+      <tr>
+        <th>In</th>
+        <th>Out</th>
+      </tr>
+      <tr>
+        <td>TBD</td>
+        <td>TBD</td>
+      </tr>
+    </table>
+  </main>
+</body>
+</html>
+

package/template/context/_templates/initiative/decisions/ADR-0000-template.md

@@ -0,0 +1,34 @@
+# ADR-0000: Decision Title
+
+Status: Proposed
+Date: YYYY-MM-DD
+
+## Context
+
+Describe the problem, constraints, forces, and options that make this
+decision necessary.
+
+## Decision
+
+State the decision clearly.
+
+## Consequences
+
+Positive:
+
+- Consequence 1
+
+Negative or tradeoffs:
+
+- Tradeoff 1
+
+## Alternatives Considered
+
+| Alternative | Why not |
+| --- | --- |
+| TBD | TBD |
+
+## Links
+
+- Related specs, PRs, tickets, discussions, or code paths.
+

package/template/context/_templates/initiative/delivery.md

@@ -0,0 +1,45 @@
+# Delivery
+
+Use this file for CI/CD, build, release, and environment-promotion behavior.
+Name the concern, not the tool. Pipeline definitions, workflow files,
+deployment scripts, release toggles, and gates can all appear here when
+relevant.
+
+Start from `context/project-profile.md` for repo-wide delivery defaults.
+Capture only initiative-specific pipeline, build, deployment, artifact, or
+release changes here.
+
+## Pipeline Impact
+
+Describe pipeline, workflow, build, packaging, or artifact changes.
+
+## Build And Release Gates
+
+List checks that must pass before merge, deployment, promotion, or release.
+
+| Gate | Applies to | Notes |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Deployment Flow
+
+Describe deployment order, environment promotion, release windows, approvals,
+and any sequencing constraints.
+
+## Feature Flags And Toggles
+
+List release flags, kill switches, configuration toggles, or staged rollout
+controls.
+
+## Delivery Automation
+
+Capture scripts, commands, CLIs, jobs, or approved automation integrations
+that agents or engineers can use to act on delivery.
+
+> Reminder: reference secrets by name. Never embed tokens, credentials, or
+> connection strings in commands or scripts captured here.
+
+## Rollout Notes
+
+Describe staged rollout, canary behavior, compatibility windows, or release
+coordination.

package/template/context/_templates/initiative/infrastructure.md

@@ -0,0 +1,41 @@
+# Infrastructure
+
+Use this file for environment shape and infrastructure dependencies. Name the
+concern, not the tool. Infrastructure modules, resource templates, manifests,
+or manual environment steps can all appear here when relevant.
+
+Start from `context/project-profile.md` for repo-wide infrastructure and
+configuration defaults. Capture only initiative-specific environment, IaC,
+resource, secret, or migration changes here.
+
+## Environment Shape
+
+Describe new or changed resources, services, networks, identity boundaries,
+storage, compute, queues, topics, or runtime hosts.
+
+## Infrastructure As Code
+
+List IaC modules, manifests, templates, parameters, or state changes.
+
+| Resource or module | Change | Location | Status |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | Todo |
+
+## Configuration And Secrets
+
+List environment variables, app settings, feature flags, secrets, certificates,
+secret manager references, or secret-rotation needs.
+
+> Reminder: never paste secret values here. Record secret names, env var keys,
+> and vault or secret-manager paths only -- never actual credentials, tokens,
+> certificates, or connection strings. Treat this file as if it were public.
+
+## Environment Dependencies
+
+Capture dependencies between environments, regions, tenants, subscriptions,
+clusters, accounts, or shared services.
+
+## Compatibility And Migration
+
+Describe infrastructure compatibility windows, provisioning order, migration
+constraints, or cleanup work.

package/template/context/_templates/initiative/interface.md

@@ -0,0 +1,41 @@
+# Interface
+
+## Purpose
+
+Describe how humans, clients, APIs, configuration, reports, or tools
+interact with this initiative.
+
+## Surfaces
+
+- UI:
+- API:
+- CLI or scripts:
+- Configuration:
+- Reports or exports:
+
+Remove surfaces that do not apply.
+
+## Workflows
+
+Describe the user, operator, support, or integration workflows.
+
+## Inputs And Outputs
+
+| Surface | Inputs | Outputs |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## States And Feedback
+
+Capture loading, empty, success, validation, warning, and error states when
+they apply.
+
+## Permissions
+
+Describe who can see, change, trigger, approve, or audit the behavior.
+
+## Terminology
+
+Record terms that must stay consistent across UI, API, docs, logs, and
+support language.
+

package/template/context/_templates/initiative/operations.md

@@ -0,0 +1,47 @@
+# Operations
+
+Use this file only when the initiative has actionable runtime, support,
+observability, rollback, or repair implications.
+
+If there is nothing concrete for an agent or engineer to act on, omit this
+file after copying the template or mark it as not applicable. Delivery belongs
+in `delivery.md`; environment shape and IaC belong in `infrastructure.md`.
+
+Start from `context/project-profile.md` for repo-wide observability, support,
+rollback, and repair entry points. Capture only initiative-specific actionable
+runtime or support changes here.
+
+## Runtime Behavior
+
+Describe how the live system behaves after the initiative ships, especially
+jobs, schedules, queues, topics, subscriptions, retries, degraded modes, or
+runtime compatibility constraints.
+
+## Observability And Support Signals
+
+Capture logs, metrics, traces, dashboards, alerts, health checks, support
+signals, and customer-visible symptoms.
+
+## Failure Modes
+
+Describe expected failures, retries, poison-message behavior, timeouts,
+partial outages, degraded modes, and support signals.
+
+## Rollback And Recovery
+
+Describe how to recover from bad runtime behavior. Include whether rollback is
+safe, whether roll-forward is required, and what state must be repaired.
+
+## Data Operations And Repair
+
+Capture migrations, backfills, cleanups, retention, repair scripts, manual
+support procedures, and validation queries.
+
+> Reminder: redact secrets, connection strings, and personal data from any
+> logs, queries, or procedures recorded here.
+
+## Actionable Tooling
+
+List CLIs, scripts, dashboards-as-code, alerts-as-code, or other approved
+automation integrations that agents or engineers can use. If none exists, say
+so explicitly.

package/template/context/_templates/initiative/plan.md

@@ -0,0 +1,23 @@
+# Plan
+
+Working alignment space — may be messy. Promote settled truth via `dive-into-plan`, not by expanding this file alone.
+
+Use `plan-with-context` for the full change-surface checklist (code, tests, e2e, IaC, CI/CD, config, ops, security, reference impact).
+
+## Current Alignment
+
+
+
+## Open Questions
+
+
+
+## Options Considered
+
+| Option | Pros | Cons | Status |
+| --- | --- | --- | --- |
+| | | | |
+
+## Notes To Promote
+
+- [ ] Items to move into per-concern docs or `decisions/` during `dive-into-plan`

package/template/context/_templates/initiative/release-doc-notes.md

@@ -0,0 +1,34 @@
+# Release Doc Notes
+
+Use this file to capture reference impact while development is
+in progress. At release time, these notes help refresh `reference/`
+against the final shipped behavior.
+
+Do not edit `reference/` from normal development work unless a human
+explicitly asks for a reference refresh or a specific reference fix.
+
+## Product Behavior Changes
+
+- None yet.
+
+## Candidate Reference Areas
+
+- `reference/<Area>/README.md`
+- `reference/<Area>/features/<feature>.md`
+
+## QA Or Support Notes
+
+- None yet.
+
+## Exclusions
+
+Record details that were considered but should not be documented because
+they are internal implementation details, temporary scaffolding, or did not
+ship.
+
+## Release-Time Checklist
+
+- [ ] Compare this initiative against the final shipped code.
+- [ ] Update the relevant reference only after release-doc work
+      is explicitly requested.
+- [ ] Add the release row if the reference workflow requires it.

package/template/context/_templates/initiative/spec.md

@@ -0,0 +1,35 @@
+# Spec
+
+## Purpose
+
+Describe what the system should do and why this behavior matters.
+
+## Goals
+
+- Goal 1
+- Goal 2
+
+## Non-Goals
+
+- Non-goal 1
+
+## Behavior
+
+Describe the expected behavior in product or domain language. Include:
+
+- Normal flow
+- Permission rules
+- Data rules
+- Validation rules
+- Error behavior
+- Edge cases
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Dependencies
+
+- Related initiatives, systems, teams, services, or decisions.
+

package/template/context/_templates/initiative/testing.md

@@ -0,0 +1,45 @@
+# Testing
+
+Use this file for the initiative's verification strategy. Name the concern,
+not the tool. Specific test runners, unit test frameworks, contract tests, or
+manual scripts can all appear here when they are relevant.
+
+Start from `context/project-profile.md` for repo-wide default commands and
+test tooling. Capture only initiative-specific additions, exceptions, data
+needs, or release gates here.
+
+## Test Strategy
+
+Describe what must be proven before this initiative can ship.
+
+## Automated Coverage
+
+List unit, integration, contract, e2e, smoke, regression, or performance tests
+that should be added or updated.
+
+| Area | Coverage | Tool or location | Status |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | Todo |
+
+## Manual Verification
+
+List any human verification that remains necessary.
+
+- None identified yet.
+
+## Test Data And Environments
+
+Capture required accounts, seeded data, fixtures, environment assumptions, or
+data cleanup needs.
+
+## Release Gates
+
+List the checks that must pass before release.
+
+- Existing CI test suite passes.
+
+## Known Gaps
+
+List accepted test gaps, why they are acceptable, and what would close them.
+
+- None identified yet.

package/template/context/project-profile.md

@@ -0,0 +1,67 @@
+# Project Profile
+
+Project: PROJECT_NAME
+Last reviewed: Not recorded
+
+Repo-wide operating facts for agents. Initiative-specific detail lives under `context/initiatives/`. Record source-backed facts only; use `Unknown` when not yet reviewed.
+
+## Repository Shape
+
+| Concern | Location | Notes |
+| --- | --- | --- |
+| Application or package code | Unknown | |
+| Tests | Unknown | |
+| CI/CD and delivery | Unknown | |
+| Infrastructure and config | Unknown | |
+| Generated artifacts | Unknown | |
+| Reference material | `reference/` | If reference-docs is installed |
+| Decision log | `decisions/` | Append-only |
+| Working context | `context/` | Disposable initiatives |
+
+## Stack And Runtime
+
+| Layer | Technology | Source | Notes |
+| --- | --- | --- | --- |
+| Runtime or language | Unknown | | |
+| Package manager | Unknown | | |
+| Frameworks | Unknown | | |
+| Data stores or services | Unknown | | |
+| Hosting or runtime platform | Unknown | | |
+
+## Commands
+
+| Concern | Command | Source | Notes |
+| --- | --- | --- | --- |
+| Install dependencies | Unknown | | |
+| Run locally | Unknown | | |
+| Build | Unknown | | |
+| Lint, format, or typecheck | Unknown | | |
+| Unit or integration tests | Unknown | | |
+| E2E or smoke tests | Unknown | | |
+| Package or release | Unknown | | |
+
+## Verification Profile
+
+- Default test expectation: Unknown.
+- Required release gates: Unknown.
+- Manual checks: Unknown.
+- Test data and environment dependencies: Unknown.
+
+## Delivery Profile
+
+- CI/CD workflow files: Unknown.
+- Deployment entry points: Unknown.
+- Environments and promotion flow: Unknown.
+- Artifacts and publishing flow: Unknown.
+
+## Infrastructure And Configuration
+
+- IaC or config roots: Unknown.
+- Managed services: Unknown.
+- Secrets references (names only): Unknown.
+- Environment dependencies: Unknown.
+
+## Operations Profile
+
+- Logs, metrics, alerts: Unknown.
+- Rollback and repair tooling: Unknown.