From 76a134b0df4459bf0df7a808823facd0054a1b24 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 30 Jun 2026 07:00:12 +0200 Subject: [PATCH] refactor(aidd-context): dedupe project-memory templates and lighten actions Memory generation restated the same fact across files (architecture vs codebase-map, integration internal flow, stack libs) because templates overlapped and the fill ran blind in parallel. Reframe ownership so each fact has one home and others reference it. Templates - architecture: drop Structure (codebase-map owns areas + entry point); Stack lists cross-cutting libs only, a capability's lib lives in its file - integration: reframe to external/third-party services (drop Internal, which duplicated architecture's flow) - api/navigation: scope routes to server vs client Actions / rules - 03: fill is no longer blind in parallel; each template knows what earlier ones captured - SKILL: split rules into Memory rules (content) and Action rules (process); add "one fact, one file" with the define-here / reference-elsewhere nuance - 04: semantic dedup review step (no fact's definition duplicated) - new references/memory-block.md; drop capability-signals' redundant section Validated headless on three stacks (cli, kairos web/mobile, kairos existing): definition-level duplication gone, files stay self-contained. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 1 + .../skills/02-project-memory/SKILL.md | 23 +++++++++++-------- .../actions/01-init-context-file.md | 16 ++++--------- .../actions/02-scaffold-docs.md | 7 +++--- .../actions/03-generate-memory.md | 21 +++++------------ .../actions/04-review-memory.md | 11 +++++---- .../actions/05-sync-memory.md | 5 ++-- .../assets/templates/memory/api/api.md | 2 +- .../templates/memory/api/integration.md | 12 ++++------ .../templates/memory/core/architecture.md | 7 +----- .../assets/templates/memory/ui/navigation.md | 2 +- .../references/capability-signals.md | 9 -------- .../references/memory-block.md | 12 ++++++++++ 13 files changed, 55 insertions(+), 73 deletions(-) create mode 100644 plugins/aidd-context/skills/02-project-memory/references/memory-block.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 7f5e99a8..5ae109d5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -82,6 +82,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [README.md](skills/02-project-memory/README.md) | - | | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - | | `references` | [mapping-ai-context-file.md](skills/02-project-memory/references/mapping-ai-context-file.md) | - | +| `references` | [memory-block.md](skills/02-project-memory/references/memory-block.md) | - | | `-` | [SKILL.md](skills/02-project-memory/SKILL.md) | `Initialize or refresh the project memory bank. Use when the user wants to set up or regenerate the project's memory files. Not for updating one memory file after it exists or editing a single rule directly.` | #### `skills/03-context-generate` diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index 05b9ae55..e5957086 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -20,22 +20,27 @@ Bootstraps the project's context layer: the AI context files with a memory block Run the actions in order, `01 → 05`, and run each action's `## Test` before the next. -## Transversal rules +## Memory rules -- Capture the macro picture and the non-derivable: decisions, conventions, gotchas, the why. Never restate derivable detail (a full schema, a file tree). Prefer a pointer to the code over a copy. -- Keep each memory file small. Bullets stay short, code in backticks, no version number in a tech name (`React`, not `React 19`). -- Memory files document the user's project, never AIDD's own scaffold. -- Reflect the current state only. Drop an unused section, no empty placeholder survives. -- Ask the user before including or excluding anything ambiguous. Never decide silently. -- Write files, never display their content. +Govern the content of every memory file. -## Loading +- Capture the macro and the non-derivable: decisions, conventions, gotchas, the why. Never restate a schema or a file tree. Point to the code over a copy. +- One fact, one file: define it in its home, elsewhere reference it. Naming a shared lib in its own concern is fine. +- Keep each file small. Short bullets, code in backticks, no version in a tech name (`React`, not `React 19`). +- Reflect the current state only. Drop an unused section, never leave a placeholder. -The core concerns load always. The `internal/` and `external/` directories are listed for on-demand reading, never auto-loaded. +## Action rules + +Govern how every action runs. + +- Read an asset or reference relative to this skill. If one can't be read, stop and say so, never invent. +- Ask before anything ambiguous. Never default silently. +- End with a short report of what changed. ## References - `references/mapping-ai-context-file.md`: the per-tool context-file path. +- `references/memory-block.md`: the context-file memory block and its upsert cases. - `references/capability-signals.md`: the capabilities, their signals, and the concerns each gates. ## Assets diff --git a/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md b/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md index 9bdb3044..f8836a6d 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/01-init-context-file.md @@ -1,6 +1,6 @@ # 01 - Init context file -Resolve the target tools, then ensure each tool's AI context file carries the project memory block. +Ensure each target tool's AI context file carries the project memory block. ## Input @@ -12,17 +12,9 @@ One context file per confirmed tool, each carrying an empty `` block after the `### Project memory` heading. - - Block present: leave it, report "already ok". -5. **Report.** Print a table: tool, file, action taken. +1. **Detect.** Find the context files already present, by the per-tool paths in `@../references/mapping-ai-context-file.md`. Only those paths qualify; any other file is user content, off-limits. +2. **Resolve tools.** On a re-run, the tools present are the confirmed set, skip the prompt. Otherwise propose the detected tools plus the full list and ask which the user uses; wait for an explicit pick, never default to all. +3. **Upsert.** For each confirmed tool, write the memory block into its context file per `@../references/memory-block.md`. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md index b2f99bc4..3056898c 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md @@ -1,6 +1,6 @@ # 02 - Scaffold docs -Create the `aidd_docs/` structure with its root docs and empty memory subdirectories. +Create the `aidd_docs/` structure: root docs and empty memory subdirectories. ## Input @@ -12,10 +12,9 @@ The project root. ## Process -1. **Docs.** For each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`: write it from the matching `@../assets/` template if absent, or update it in place while preserving the user's customizations. +1. **Docs.** Write each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md` from its `@../assets/` template if absent, else update in place preserving the user's edits. 2. **Memory dirs.** Ensure `aidd_docs/memory/internal/` and `aidd_docs/memory/external/` exist, each with a `.gitkeep`. -3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent, leaving an existing one untouched. -4. **Report.** Print a table: path, action taken (created, updated, or skipped). +3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent; leave an existing one. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md b/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md index 6169aa59..0e719f72 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/03-generate-memory.md @@ -8,24 +8,15 @@ The `aidd_docs/memory/` directory and the project root. ## Output -The `core/` memory files plus the folder of each detected capability, filled and written flat to `aidd_docs/memory/`. +The `core/` memory files plus each detected capability's folder, filled and written flat to `aidd_docs/memory/`. ## Process -1. **Gate.** Read one template (e.g. `@../assets/templates/memory/core/architecture.md`). If it cannot be read, stop: the templates are unreachable. Never invent content. -2. **Detect.** Find the project's capabilities (`@../references/capability-signals.md`). A capability holds when a concrete fact in the repo matches its definition, whether or not the fact is in the Evidence column. Never fire on an inferred domain. In a monorepo, scan every workspace, not the root manifest alone. -3. **Confirm.** Show each detected capability with the concrete evidence behind it and the templates it selects. Ask the user to confirm, add, or drop one. Block on the answer. -4. **Select.** Take every template in `core/`, plus every template in each confirmed capability's folder (`@../references/capability-signals.md`). -5. **Reconcile.** If `aidd_docs/memory/` already holds files: - - A selected concern with an existing file: update it from current reality, preserving the user's edits. - - A selected concern with no file: create it. - - An existing file whose capability is no longer detected: leave it, flag it to the user, never delete. -6. **Fill.** For each selected template, in parallel: - - Read its sections. - - Capture the macro and non-derivable facts from the project, excluding AIDD's own scaffold. Prefer a pointer to the code over a copy. - - Fill the sections. Drop a section with no content. Strip the guidance comment. Never copy a template verbatim, ask the user instead. -7. **Write.** One output per template, named by the template's basename, flat at `aidd_docs/memory/`. Never nest, never rename, never consolidate. -8. **Report.** A table: capability, concern, output file, status (created, updated, kept, or flagged). +1. **Detect.** Find the project's capabilities (`@../references/capability-signals.md`): a capability holds when a concrete repo fact matches its definition, never an inferred domain. In a monorepo, scan every workspace. +2. **Confirm.** Show each capability with its evidence and the templates it selects. Ask the user to confirm, add, or drop one. Block on the answer. +3. **Select.** Take `core/` plus each confirmed capability's folder. On an existing `aidd_docs/memory/`: update a concern from current reality (keep the user's edits), create a missing one, leave-but-flag one whose capability is gone (never delete). +4. **Fill.** For each template, knowing what earlier ones captured (never repeat a fact, point to its file): capture the macro, non-derivable facts (exclude AIDD's scaffold, point to code over a copy), fill its sections, drop an empty one, strip the guidance comment, never copy verbatim. +5. **Write.** One file per template, named by its basename, flat in `aidd_docs/memory/`. Never nest, rename, or consolidate. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md b/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md index af1b5cba..ec72b87b 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/04-review-memory.md @@ -1,6 +1,6 @@ # 04 - Review memory -Review every memory file together for cross-file consistency, and fix what is safe. +Review every memory file together for cross-file consistency and duplication, fixing what is safe. ## Input @@ -8,14 +8,15 @@ The `aidd_docs/memory/` directory with the generated files. ## Output -The memory files, corrected in place where needed, and a status table. +The memory files, corrected in place where safe, and a status report. ## Process 1. **Read.** Load every `.md` under `aidd_docs/memory/`, recursively. -2. **Review.** In one pass with all files in context, check consistency and accuracy across them. Fix a safe inconsistency in place. Flag one that needs a human. -3. **Report.** A table: file, status (clean, fixed with reason, or needs review). +2. **Review.** In one pass, check cross-file consistency and accuracy. Fix a safe issue in place, flag one that needs a human. +3. **Deduplicate.** Keep each fact in one file, drop the copies (judge by meaning, not wording). May be handed to an independent checker subagent. ## Test -- The status table covers every memory file, and each flagged file carries a reason a human can act on. +- Every memory file is covered by the report, each flagged file with a reason a human can act on. +- No fact's definition is duplicated across files. diff --git a/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md b/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md index 1eee4349..b7c613c0 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/05-sync-memory.md @@ -12,9 +12,8 @@ Each `` block lists the generated memory files as reference ## Process -1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to inject the references. -2. **Guard.** On a non-zero exit, print the error and stop. Tell the user to confirm `aidd_docs/memory/` holds a `.md` file and that `node` is available. -3. **Report.** Print how many context files were updated and how many references went into each block, then list the references per file. +1. **Run.** Execute the memory-sync script (`update_memory.js` in the plugin's `hooks/`) to fill each block (the block: `@../references/memory-block.md`). +2. **Guard.** On a non-zero exit, print the error and stop; tell the user to check that `aidd_docs/memory/` holds a `.md` file and that `node` is available. ## Test diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md index 7145a102..54935d4f 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/api.md @@ -4,7 +4,7 @@ The HTTP API surface: its style, the main resources, and the contracts. ## Style -- +- - ## Resources diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md index 19c53b77..5896eee9 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/api/integration.md @@ -1,10 +1,6 @@ # Integration -How this system talks to others: internal communication and external services. - -## Internal - -- +How this system integrates with external/third-party services. ## External services @@ -12,10 +8,10 @@ How this system talks to others: internal communication and external services. ```mermaid flowchart LR - A[TODO: macro communication between this system and its services] + A[TODO: macro map of this system and its external services] ``` diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md index c921be86..3d844383 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/core/architecture.md @@ -5,12 +5,7 @@ The macro technical shape: the stack, how the pieces fit, and the decisions behi ## Stack - -- - -## Structure - -- -- +- ## How it fits together diff --git a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md index 2a5b1ba7..8787d1e7 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/templates/memory/ui/navigation.md @@ -4,7 +4,7 @@ How the user moves through the app: routing and the page structure. ## Routing -- +- - ## Structure diff --git a/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md b/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md index 2a8ca8ef..bb00ba40 100644 --- a/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md +++ b/plugins/aidd-context/skills/02-project-memory/references/capability-signals.md @@ -23,12 +23,3 @@ A capability holds when a concrete fact in the repo matches the capability's **d | `cli` | is run as a command-line tool | a `bin` field, or a CLI-parser dependency (commander, yargs, oclif, clap, click) | cli | | `data` | processes data or trains models | notebooks, a data-versioning or ML tool, or pipeline and model files | data | | `monorepo` | hosts several packages in one repo | workspaces, or a monorepo tool (Turborepo, Nx, Lerna) | enriches `core/codebase-map` (the Packages section), no folder | - -## How the action uses this - -- Always generate every template in `core/`. -- For each capability that holds, generate every template in its folder. -- Fire a capability on a concrete fact that matches its definition, whether or not the fact is in the Evidence column. Never fire on an inferred domain. -- A capability with no concrete fact produces no file. -- A monorepo fills the Packages section of `codebase-map`, it has no folder of its own. -- In a monorepo, gather facts across every workspace, not the root manifest alone. A capability holds when any one workspace shows it (a React app in `packages/web` means `ui` holds for the project). diff --git a/plugins/aidd-context/skills/02-project-memory/references/memory-block.md b/plugins/aidd-context/skills/02-project-memory/references/memory-block.md new file mode 100644 index 00000000..1c7c7b98 --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/references/memory-block.md @@ -0,0 +1,12 @@ +# Memory block + +The `` block is where a tool's AI context file points to the generated memory files. It sits under `## Memory Management` → `### Project memory` (full template: `@../assets/AGENTS.md`). + +## Upsert + +Apply the first case that matches a tool's context file: + +- **Absent:** copy `@../assets/AGENTS.md`, set the tool's title. +- **No `## Memory Management`:** append that section from the template. +- **Section but no block:** insert an empty `` block after `### Project memory`. +- **Block present:** leave it, report "already ok".