ctx-lessons 0.1.0__tar.gz

ctx_lessons-0.1.0/.claude/skills/aidlc/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: aidlc
+description: Drive a unit of work through the AI Development Lifecycle. Use when the user says "/aidlc", asks to start a slice / epic / new feature, asks to pick up a queued issue, or says anything like "let's do AI-DLC on X", "start inception for X", "move X to construction", "scaffold a slice for X". Also use to log out-of-band chore work into the project audit trail.
+---
+
+# AI-DLC
+
+Drives work through the AI Development Lifecycle. This skill is the executable wrapper: triage the request, scaffold the right artefacts, walk the right stages, keep the audit trail honest.
+
+The process follows the AWS canvas (`awslabs/aidlc-workflows`), adapted with TDD, vertical slices, and brownfield reverse engineering where needed. When in doubt: phase names, ALWAYS/CONDITIONAL, FD-before-NFR, TG-before-CG are load-bearing.
+
+## Reference docs
+
+- `TEMPLATES/` (this skill) — copy-ready scaffolds for slice folders and audit entries
+- `aidlc-docs/<slice>/audit.md` — append-only log of AI decisions + user approvals for that slice
+- `aidlc-docs/<slice>/aidlc-state.md` — current phase/stage progress for that slice
+
+No project-wide tracker. Audit and state live **only** under the slice they belong to. Recipe and chore work do not get audit entries — trust `git log` and PR descriptions.
+
+## Triage — pick the right process
+
+Three flavours of work. **Pick before scaffolding anything.**
+
+| Flavour | When to use | Process |
+|---|---|---|
+| **Greenfield slice** | New feature with non-obvious requirements, non-trivial design space, multiple units of work. | Full AI-DLC: scaffold `aidlc-docs/<slice>/`, run Inception → Construction with all artefacts, gated `[Answer]:` plans at each stage. **TG-as-RED is mandatory** — tests are written first, then code. Review Gate runs pre-PR. |
+| **Recipe / sweep** | Mechanical work following a known pattern. | Light: append one audit entry at start ("CONSTRUCTION - Code Generation"), execute, append one at end ("Build and Test"). No per-slice folder. Skip TG-as-RED (work is mechanical); still run `security-review` + `simplify` as a mini Review Gate before PR. |
+| **Chore / infra / ops** | Repo restructure, CI tweaks, doc migration, branch cleanup. No slice equivalent. | Minimal: single audit entry on completion. No per-slice folder, no state-file slice rows. No TG, no Review Gate. May still create issues for tracking. |
+
+If unsure, ask the user. Don't auto-promote a recipe to a greenfield slice — that wastes inception cycles.
+
+## Greenfield slice — the full path
+
+### 1. Inception
+
+Create the slice scaffold:
+
+```bash
+SLICE=<snake_case_feature_name>     # should match code structure where applicable
+mkdir -p aidlc-docs/$SLICE/{inception/{plans,reverse-engineering,user-stories,application-design},construction}
+cp .claude/skills/aidlc/TEMPLATES/slice-audit.md           aidlc-docs/$SLICE/audit.md
+cp .claude/skills/aidlc/TEMPLATES/slice-aidlc-state.md     aidlc-docs/$SLICE/aidlc-state.md
+# Replace <SLICE> placeholder in both files with $SLICE
+sed -i '' "s|<SLICE>|$SLICE|g" aidlc-docs/$SLICE/audit.md aidlc-docs/$SLICE/aidlc-state.md
+```
+
+Inception stages, in canvas order. ALWAYS stages run every slice; CONDITIONAL stages run when they add value. Each stage produces a plan with `[Answer]:` tags first (where listed), gets user confirmation, then produces the artefact:
+
+| # | Stage | Freq | Plan file | Artefact |
+|---|---|---|---|---|
+| 1 | Workspace Detection | ALWAYS | *(automatic, no plan)* | `inception/workspace-detection.md` |
+| 2 | Reverse Engineering | CONDITIONAL (brownfield) | `inception/plans/reverse-engineering-plan.md` | `inception/reverse-engineering/{code-structure,domain-model,integration-map}.md` |
+| 3 | Requirements Analysis | ALWAYS | `inception/plans/requirements-analysis-plan.md` | `inception/requirements-analysis.md` |
+| 4 | User Stories | CONDITIONAL | `inception/plans/story-generation-plan.md` | `inception/user-stories/{stories,personas}.md` |
+| 5 | Application Design (DDD) | CONDITIONAL | `inception/plans/application-design-plan.md` | `inception/application-design/{unit-of-work,unit-of-work-dependency,unit-of-work-story-map}.md` |
+| 6 | Units Generation (vertical slices) | CONDITIONAL | `inception/plans/units-generation-plan.md` | Work units defined, tracking issues created (optional) |
+| 7 | Workflow Planning | ALWAYS | `inception/plans/workflow-planning-plan.md` | `inception/workflow-planning.md` — names which Construction stages run per unit |
+
+Most work is brownfield. Reverse Engineering runs for any slice touching existing code — that's nearly every slice. Skip it only for slices creating wholly new modules with no overlap.
+
+At end of inception:
+- All inception-gate checkboxes ticked in `aidlc-docs/<slice>/aidlc-state.md`
+- Any tracking issues created (optional, per project preference)
+- All work units identified and sequenced
+
+### 2. Construction
+
+For each unit of work, in dependency order. **Canvas stage order — do not reorder.** FD before NFR is load-bearing; TG (RED) before CG (GREEN) is non-negotiable.
+
+| # | Stage | Freq | TDD | Artefact |
+|---|---|---|---|---|
+| 1 | Functional Design | CONDITIONAL | — | `construction/functional-design.md` — business logic per unit |
+| 2 | NFR Requirements | CONDITIONAL | — | `construction/nfr-requirements.md` — NFRs + tech stack |
+| 3 | NFR Design | CONDITIONAL | — | `construction/nfr-design.md` |
+| 4 | Infrastructure Design | CONDITIONAL | — | `construction/infrastructure-design.md` |
+| 5 | **Test Generation** | **ALWAYS** | **RED** | `construction/test-generation.md` + failing tests on branch |
+| 6 | **Code Generation** | **ALWAYS** | **GREEN + REFACTOR** | minimal code to pass tests, then refactor; tests green |
+| 7 | Build and Test | ALWAYS | — | full suite green (integration + e2e where applicable) |
+| 8 | **Review Gate** | ALWAYS | — | `construction/review-gate.md` — parallel review battery passes; advisory findings filed as follow-up issues |
+| 9 | PR Merged | ALWAYS | — | PR opened with `review-gate.md` linked, merged, Task issue closed |
+
+Track work progress through stages: `Ready → In Development → In Review → Completed`. `In Review` is set only after the **Review Gate** passes and the PR is opened.
+
+### Review Gate (mandatory pre-PR)
+
+See [`docs/agents/aidlc.md`](../../../docs/agents/aidlc.md#review-gate) for the full spec. Quick reference:
+
+- **Run in parallel**, after local tests pass, before `gh pr create`.
+- **Greenfield:** `security-review`, `simplify`, and an agent-driven **correctness pass** against `stories.md` + `functional-design.md`.
+- **Recipe:** `security-review` + `simplify` only.
+- **Chore:** skip entirely.
+- **Never invoke `/ultrareview`** — user-triggered only. Recommend it for auth/payments/PII slices; don't launch it.
+
+**Blocking** (PR does not open until fixed):
+- `security-review` HIGH/CRITICAL
+- Correctness pass finds an unmet acceptance criterion
+
+**Advisory** (file follow-up issue, do NOT fix in this PR — prevents scope sprawl):
+- `simplify` findings
+- Test-quality advisories
+
+Write `aidlc-docs/<slice>/construction/review-gate.md` with verdicts, follow-up issue numbers, and re-run history. Link it in the PR description. For recipes, append the gate block to the recipe's audit entry instead of creating a slice folder.
+
+### 3. Documentation pass
+
+When the slice closes, update any relevant project documentation with learnings from the slice. This might include:
+- Updating CONTEXT.md with new terminology or domain clarifications
+- Recording decisions in a project ADR if they affect architecture
+- Updating README.md with new features or changed behavior
+
+## Recipe / sweep — the light path
+
+No slice folder, no audit entry. Do the work, ship the PR, write a clear commit message + PR description. `git log` is the record.
+
+## Chore / infra — minimal
+
+Same as recipe: no slice folder, no audit. Commit message + PR description carries the why.
+
+## Audit-log schema (per-slice `aidlc-docs/<slice>/audit.md`)
+
+Greenfield slices keep an append-only audit trail. Each entry:
+
+```markdown
+---
+
+## <STAGE> - <short description>
+**Timestamp**: <ISO-8601 UTC>
+**User Input**: "<verbatim or summarised user request>"
+**AI Response**: "<what you did, terse, decision-focused>"
+**Context**: <one-line note>
+
+[optional]
+**Process note**: <why this entry exists out of normal AI-DLC flow>
+
+---
+```
+
+`<STAGE>` is one of: `INCEPTION - <stage>`, `CONSTRUCTION - <stage>`.
+
+## State-file update rules
+
+`aidlc-docs/<slice>/aidlc-state.md` — checkboxes for the slice's own stages. Greenfield only. Update at the same commit as the artefact it represents — never split.
+
+## Invocation patterns
+
+- `/aidlc` (no args) — show current state: scan `aidlc-docs/*/aidlc-state.md` for the active slices' current stages; suggest next pickups from open issues.
+- `/aidlc start <slice-name>` or "start AI-DLC on the auth slice" — triage, scaffold if greenfield, begin Inception stage 1.
+- `/aidlc continue` or "continue the auth slice" — read the slice's `aidlc-state.md`, identify the next unchecked stage, resume there.
+- `/aidlc close <slice>` — verify all task issues closed, kick off living-docs pass, mark slice complete in `aidlc-docs/<slice>/aidlc-state.md`.
+
+## When NOT to use this skill
+
+- Bug-fix PRs not tied to a slice → use `diagnose` or `triage-issue`.
+- Creating issues from scratch → use `to-issues` or `to-prd` first; this skill picks up after the epic exists.
+- VS Code config tweaks, dependency bumps → just do it. Don't manufacture an audit entry for noise.
+
+## Discipline reminders
+
+- `audit.md` is **append-only**. Never edit past entries — add a follow-up entry if a decision is reversed.
+- PiT records in `aidlc-docs/<slice>/` are **frozen at slice close**. Corrections go to the wiki, not back into the slice folder.
+- Plans use `[Answer]: <maintainer's answer>` tags so the human gate is preserved in the artefact.
+- Snake_case slice names should match code structure and be consistent across artefacts.

ctx_lessons-0.1.0/.claude/skills/aidlc/TEMPLATES/slice-aidlc-state.md

@@ -0,0 +1,41 @@
+# <SLICE> — AI-DLC state
+
+## Slice info
+- **Slice name**: `<SLICE>`
+- **Issue tracking**: *(if using GitHub/Linear/etc, link here)*
+- **Design doc**: `docs/<SLICE>.md` or inline in audit.md *(if applicable)*
+- **Status**: Inception — not started
+- **Blocker**: None
+
+## Inception
+- [ ] Workspace detection — artefact
+- [ ] Reverse engineering — artefact *(if touching existing code)*
+- [ ] Requirements analysis — plan
+- [ ] Requirements analysis — artefact
+- [ ] Story generation — plan
+- [ ] Story generation — artefact
+- [ ] Workflow planning — plan
+- [ ] Workflow planning — artefact
+- [ ] Application design — plan
+- [ ] Application design — artefact (unit-of-work + dependency + story-map)
+- [ ] Units generation — plan
+- [ ] Units generation — work units defined and sequenced
+
+## Construction
+*(populate one block per unit of work after units-generation completes)*
+
+### Unit: <unit-name>
+- [ ] Functional Design *(if needed)*
+- [ ] NFR Requirements *(if needed)*
+- [ ] NFR Design *(if needed)*
+- [ ] Infrastructure Design *(if applicable)*
+- [ ] Test Generation (RED)
+- [ ] Code Generation (GREEN)
+- [ ] Build and Test
+- [ ] Review Gate pass
+- [ ] PR merged
+
+## Slice close
+- [ ] All work units completed
+- [ ] Documentation updated with slice learnings
+- [ ] Slice marked complete in this state file

ctx_lessons-0.1.0/.claude/skills/aidlc/TEMPLATES/slice-audit.md

@@ -0,0 +1,17 @@
+# <SLICE> — AI-DLC audit log
+
+Append-only log of AI decisions and user approvals for the `<SLICE>` slice. Never edit past entries — add a follow-up entry if a decision is reversed or refined.
+
+Entry schema:
+
+```
+---
+
+## <STAGE> - <slice>
+**Timestamp**: <ISO-8601 UTC>
+**User Input**: "..."
+**AI Response**: "..."
+**Context**: ...
+
+---
+```

ctx_lessons-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # allows the release workflow to reuse this as a gate
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest

ctx_lessons-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,81 @@
+name: Release
+
+# Publishes the `ctx-lessons` distribution (installs the `ctx` command).
+#
+# Two paths:
+#   * push a tag `vX.Y.Z`  -> builds, gates on CI, publishes to PyPI
+#   * manual dispatch      -> builds and publishes to TestPyPI for a dry run
+#
+# Auth is PyPI Trusted Publishing (OIDC) — no API tokens stored in this repo.
+# Requires a pending publisher configured at
+# https://pypi.org/manage/account/publishing/ for repo brandonajlowe/ctx-engine,
+# workflow `release.yml`, environment `pypi` (and `testpypi` for the dry run).
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Check tag matches project version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          project="$(uv version --short)"
+          if [ "$tag" != "$project" ]; then
+            echo "::error::tag v$tag does not match pyproject version $project"
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Smoke-test the built wheel
+        run: uvx --from ./dist/*.whl ctx --version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

ctx_lessons-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# venv
+.venv/
+.python-version
+
+# build
+dist/
+build/
+
+# editor
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# test artefacts pointing at ~/.ctx
+tmp/

ctx_lessons-0.1.0/CONTEXT.md

@@ -0,0 +1,43 @@
+# CONTEXT — `ctx` glossary
+
+Canonical terms used across PRD, AIDLC artefacts, code, and lesson frontmatter. Locked at Requirements Analysis. Any addition or rename goes through an audit-entry-tagged ADR.
+
+## Actors
+
+- **developer** — the human running `ctx` from their terminal or inside an AI coding session. Always the principal; `ctx` has no other end-user.
+- **agent** — the AI coding assistant (Claude Code, Codex CLI, Cursor, etc.) that invokes `ctx` as a subprocess. The agent is a *consumer*, not a *principal*: it acts on behalf of the developer.
+- **curator** (also: **lesson librarian**) — a developer wearing the review hat: reviews promotion PRs, runs periodic re-validation, marks lessons deprecated. Not a separate role; a rotating responsibility.
+
+## Domain nouns
+
+- **lesson** — the canonical artefact. A markdown file with YAML frontmatter, stored in the team-knowledge repo. One lesson = one curated insight.
+- **candidate** — an LLM-extracted draft lesson that has not yet been promoted. Lives in the personal layer with status `draft` or `imported-pending-review`.
+- **corpus** — the full set of lessons reachable from the local SQLite index (team layer ∪ personal layer).
+- **team-knowledge repo** — the upstream git repo containing the active (curated) lessons. One repo per team in v1.
+- **team layer** — the developer's local clone of the team-knowledge repo at `~/.ctx/team/`.
+- **personal layer** — the developer's local-only draft store at `~/.ctx/personal/`. Never synced anywhere.
+- **draft layer** — synonym for personal layer when referring to lesson lifecycle stage.
+- **scope** — a lesson's reach. One of `org`, `team:<name>`, `product:<name>`, `project:<name>`. Forms a precedence hierarchy: project > team > org for ranking ties.
+- **provenance** — the `source` block on a lesson (`type`, `ref`, `thread_id`). Tells the agent where the lesson came from.
+- **freshness** — derived signal from `created` + `last_reviewed`. Used for ranking decay and for the `ctx stale` query.
+- **supersession** — the relationship between a deprecated lesson and its replacement, expressed via `superseded_by` on the deprecated lesson.
+
+## Process verbs
+
+- **ingest** — fetch raw input from a source (GitHub PR threads via `gh`, documents from disk). No filtering, no LLM. Produces a stream of normalised raw items.
+- **filter** — pure-function pre-LLM gating: bot detection, resolution check, substantive-discussion check. Returns boolean or score. No I/O.
+- **extract** — LLM-driven lesson candidate generation. Reads filtered raw items, returns a list of candidate lessons per item. Empty list = no signal.
+- **promote** — open a PR against the team-knowledge repo's `main` branch, moving a draft lesson into the team layer. The PR is the human curation gate.
+- **deprecate** — mark a lesson superseded. Never delete; supersession history is auditable.
+- **supersede** — point a deprecated lesson at its replacement via `superseded_by`.
+- **sync** — `git pull` on `~/.ctx/team/`, then rebuild the SQLite index from team + personal layers.
+
+## Predecessor product
+
+The legacy product whose BR / NFR / decision documents seed the corpus. Scope string: **`product:<predecessor-name>`** — final name TBD by maintainer; tracked as the only `[Answer — needs-user-input]` from Requirements Analysis. Update this glossary entry once decided.
+
+## Out of glossary
+
+- *user* — ambiguous; use **developer** for the human, **agent** for the AI.
+- *memory* — implies auto-capture; `ctx` is curated, not a memory store. Use **lesson** or **corpus**.
+- *FAQ* — connotation of stale, accumulating noise; `ctx` is designed against this failure mode.

ctx_lessons-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Lowe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.