agile-context-engineering 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
<wiki-readme>
|
|
2
|
+
<purpose>
|
|
3
|
+
Template for `.docs/wiki/wiki-readme.md` — the entry point and usage guide for the
|
|
4
|
+
engineering wiki. Generated once when the `.docs/wiki/` directory is first created
|
|
5
|
+
(typically by `/ace:map-system`).
|
|
6
|
+
|
|
7
|
+
Serves two audiences:
|
|
8
|
+
- **Humans** who want to understand, navigate, and contribute to the wiki
|
|
9
|
+
- **AI agents** who need to know which documents to load for a given task
|
|
10
|
+
|
|
11
|
+
This is NOT a documentation template — it is a META-DOCUMENT that describes how the
|
|
12
|
+
wiki itself works. Think of it as the README for the wiki system.
|
|
13
|
+
</purpose>
|
|
14
|
+
|
|
15
|
+
<template>
|
|
16
|
+
<header>
|
|
17
|
+
# Engineering Wiki
|
|
18
|
+
|
|
19
|
+
Living knowledge base for this codebase. Maintained by AI agents after each story
|
|
20
|
+
and by developers when making structural changes.
|
|
21
|
+
|
|
22
|
+
**For humans**: browse by subsystem, read system and pattern docs to understand how things work.
|
|
23
|
+
**For AI agents**: load the minimal set of docs needed for your current task — every token counts.
|
|
24
|
+
</header>
|
|
25
|
+
|
|
26
|
+
<directory-structure>
|
|
27
|
+
## Directory Structure
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
.docs/wiki/
|
|
31
|
+
|-- wiki-readme.md # This file — how to use the wiki
|
|
32
|
+
|-- system-wide/ # Documents that span all subsystems
|
|
33
|
+
| |-- system-structure.md # Physical layout, subsystem index, shared dirs
|
|
34
|
+
| |-- system-architecture.md # L1/L2 C4 views, core flows, tech stack
|
|
35
|
+
| |-- testing-framework.md # Test runner, patterns, conventions
|
|
36
|
+
| |-- coding-standards.md # Language and paradigm-specific rules
|
|
37
|
+
| `-- tech-debt-index.md # Roll-up of all known tech debt
|
|
38
|
+
`-- subsystems/
|
|
39
|
+
`-- [subsystem-name]/ # One folder per subsystem
|
|
40
|
+
|-- structure.md # File layout, "where to add code"
|
|
41
|
+
|-- architecture.md # L3 components, internal flows, dependencies
|
|
42
|
+
|-- systems/ # WHAT exists — domain system docs
|
|
43
|
+
| `-- [system-name].md
|
|
44
|
+
|-- patterns/ # HOW to implement — reusable structural patterns
|
|
45
|
+
| `-- [pattern-name].md
|
|
46
|
+
|-- cross-cutting/ # Shared infrastructure spanning systems
|
|
47
|
+
| `-- [concern-name].md
|
|
48
|
+
|-- guides/ # Step-by-step implementation recipes
|
|
49
|
+
| `-- [task-name].md
|
|
50
|
+
`-- decisions/ # WHY — Architecture Decision Records
|
|
51
|
+
`-- ADR-NNN-[slug].md
|
|
52
|
+
```
|
|
53
|
+
</directory-structure>
|
|
54
|
+
|
|
55
|
+
<document-types>
|
|
56
|
+
## Document Types
|
|
57
|
+
|
|
58
|
+
### System-Wide Documents
|
|
59
|
+
|
|
60
|
+
| Document | Answers | Created By |
|
|
61
|
+
|----------|---------|------------|
|
|
62
|
+
| `system-structure.md` | What subsystems exist and where do they live? | `/ace:map-system` |
|
|
63
|
+
| `system-architecture.md` | What's the system design, tech stack, and core flows? | `/ace:map-system` |
|
|
64
|
+
| `testing-framework.md` | How do we test? Runner, patterns, conventions. | `/ace:map-system` |
|
|
65
|
+
| `coding-standards.md` | What are the mandatory code quality rules? | `/ace:init-coding-standards` |
|
|
66
|
+
| `tech-debt-index.md` | What known quality issues exist across the codebase? | `/ace:map-story` (auto) |
|
|
67
|
+
|
|
68
|
+
### Subsystem Documents
|
|
69
|
+
|
|
70
|
+
| Document | Answers | Created By |
|
|
71
|
+
|----------|---------|------------|
|
|
72
|
+
| `structure.md` | Where do files live in this subsystem? Where do I add new code? | `/ace:map-subsystem` |
|
|
73
|
+
| `architecture.md` | What are the internal components, layers, and flows? | `/ace:map-subsystem` |
|
|
74
|
+
|
|
75
|
+
### Knowledge Documents (per subsystem)
|
|
76
|
+
|
|
77
|
+
| Category | Answers | When to Create |
|
|
78
|
+
|----------|---------|----------------|
|
|
79
|
+
| `systems/` | How does this domain system work RIGHT NOW? | One doc per coherent domain capability (e.g., drawing system, order processing) |
|
|
80
|
+
| `patterns/` | How do I implement using this reusable pattern? | When a structural pattern appears in 2+ implementations |
|
|
81
|
+
| `cross-cutting/` | How does this shared infrastructure work? | For concerns spanning multiple domain systems (DI, events, registry) |
|
|
82
|
+
| `guides/` | How do I perform this recurring task end-to-end? | When a task is repeated (adding a new tool, endpoint, entity) |
|
|
83
|
+
| `decisions/` | Why was this significant choice made? | When a meaningful trade-off was evaluated and decided |
|
|
84
|
+
</document-types>
|
|
85
|
+
|
|
86
|
+
<how-to-use>
|
|
87
|
+
## How to Use This Wiki
|
|
88
|
+
|
|
89
|
+
### For Humans
|
|
90
|
+
|
|
91
|
+
**Understand a subsystem:**
|
|
92
|
+
1. Read `subsystems/[name]/architecture.md` — components, layers, internal flows
|
|
93
|
+
2. Read relevant `systems/*.md` — domain systems you care about
|
|
94
|
+
3. Follow cross-references to patterns and cross-cutting concerns
|
|
95
|
+
|
|
96
|
+
**Implement a new feature:**
|
|
97
|
+
1. Read `system-wide/coding-standards.md` — mandatory rules
|
|
98
|
+
2. Read the subsystem's `structure.md` — where to add files
|
|
99
|
+
3. Check `guides/` — there may be a step-by-step recipe for your task
|
|
100
|
+
4. Read relevant `patterns/` — follow established structural patterns
|
|
101
|
+
5. Check `decisions/` — respect past architectural decisions
|
|
102
|
+
|
|
103
|
+
**Debug or investigate:**
|
|
104
|
+
1. Start with the relevant `systems/*.md` — it has entry points, flows, and components
|
|
105
|
+
2. Follow the sequence diagrams to trace data flow
|
|
106
|
+
3. Check `cross-cutting/` for shared infrastructure behavior
|
|
107
|
+
|
|
108
|
+
### For AI Agents
|
|
109
|
+
|
|
110
|
+
**Context loading strategy:**
|
|
111
|
+
- ALWAYS load system-wide docs first: `system-structure.md`, `system-architecture.md`, `coding-standards.md`, `testing-framework.md`
|
|
112
|
+
- Then load subsystem docs for the subsystem(s) you are modifying
|
|
113
|
+
- Load ONLY the `systems/`, `patterns/`, `cross-cutting/`, and `guides/` docs relevant to your task
|
|
114
|
+
- Check `decisions/` for ADRs that constrain your design choices
|
|
115
|
+
- Every token in your context window costs reasoning capacity — load less, reason better
|
|
116
|
+
|
|
117
|
+
**Finding the right docs:**
|
|
118
|
+
- Story files include a `## Relevant Wiki` section with curated doc references
|
|
119
|
+
- Each doc cross-references related docs via markdown links — follow them as needed
|
|
120
|
+
- `structure.md` → where files live; `architecture.md` → how things connect
|
|
121
|
+
- `systems/` → domain behavior; `patterns/` → structural recipes; `guides/` → task recipes
|
|
122
|
+
</how-to-use>
|
|
123
|
+
|
|
124
|
+
<how-to-create>
|
|
125
|
+
## Creating New Wiki Documents
|
|
126
|
+
|
|
127
|
+
Wiki documents are primarily created and updated by AI agents (ace-wiki-mapper) through:
|
|
128
|
+
- `/ace:map-system` — system-wide documents
|
|
129
|
+
- `/ace:map-subsystem` — subsystem structure, architecture, and knowledge docs
|
|
130
|
+
- `/ace:map-story` — updates knowledge docs after story implementation
|
|
131
|
+
|
|
132
|
+
### Manual Creation Guidelines
|
|
133
|
+
|
|
134
|
+
If creating a document manually, follow these rules:
|
|
135
|
+
|
|
136
|
+
**Naming:**
|
|
137
|
+
- Use kebab-case for all file names: `drawing-system.md`, `repository-pattern.md`
|
|
138
|
+
- Systems: name after the domain capability — `drawing-system.md`, `order-processing.md`
|
|
139
|
+
- Patterns: name after the pattern — `template-method-pattern.md`, `repository-pattern.md`
|
|
140
|
+
- Cross-cutting: name after the concern — `dependency-injection.md`, `event-system.md`
|
|
141
|
+
- Guides: name after the task — `adding-drawing-tool.md`, `adding-crud-endpoint.md`
|
|
142
|
+
- Decisions: `ADR-NNN-kebab-slug.md` — sequential numbering within the subsystem
|
|
143
|
+
|
|
144
|
+
**Content rules:**
|
|
145
|
+
- EXTREMELY SUCCINCT — every word must add value
|
|
146
|
+
- Bullet points over paragraphs
|
|
147
|
+
- Code references: `file-path:ClassName.methodName` — never line numbers
|
|
148
|
+
- All architecture diagrams MUST be mermaid (flowchart, classDiagram, sequenceDiagram)
|
|
149
|
+
- File trees: ASCII only (`|--` and backtick for last item)
|
|
150
|
+
- Inline code ONLY for interface/type contracts
|
|
151
|
+
- Cross-reference related docs with markdown links
|
|
152
|
+
- Every `systems/*.md` MUST have at least one mermaid sequenceDiagram
|
|
153
|
+
|
|
154
|
+
**Topic-scoped, not story-scoped:**
|
|
155
|
+
- Documents describe a CONCERN, not a story or sprint
|
|
156
|
+
- "How does the drawing system work?" — good
|
|
157
|
+
- "What story #19 implemented" — wrong (that goes in `.ace/artifacts/`)
|
|
158
|
+
|
|
159
|
+
**Create vs update decision:**
|
|
160
|
+
1. Does an existing doc already cover this topic? → UPDATE it
|
|
161
|
+
2. Could this be a new section in an existing doc? → Add the section
|
|
162
|
+
3. Any overlap with existing docs? → Merge into the existing doc
|
|
163
|
+
4. Genuinely new topic with no overlap? → CREATE a new doc
|
|
164
|
+
</how-to-create>
|
|
165
|
+
|
|
166
|
+
<keeping-current>
|
|
167
|
+
## Keeping the Wiki Current
|
|
168
|
+
|
|
169
|
+
### Automatic Updates
|
|
170
|
+
|
|
171
|
+
After each story implementation, `/ace:map-story` analyzes git changes and updates
|
|
172
|
+
the relevant knowledge documents. This is the primary mechanism for keeping the wiki
|
|
173
|
+
current.
|
|
174
|
+
|
|
175
|
+
### Manual Update Triggers
|
|
176
|
+
|
|
177
|
+
**Update `system-structure.md` when:**
|
|
178
|
+
- New subsystem added, removed, or merged
|
|
179
|
+
- Shared directory added or removed
|
|
180
|
+
- Workspace configuration changed
|
|
181
|
+
|
|
182
|
+
**Update `system-architecture.md` when:**
|
|
183
|
+
- New subsystem or external integration added
|
|
184
|
+
- Communication pattern changed
|
|
185
|
+
- Tech stack changed
|
|
186
|
+
|
|
187
|
+
**Update `testing-framework.md` when:**
|
|
188
|
+
- Test runner or mocking approach changed
|
|
189
|
+
- Coverage requirements changed
|
|
190
|
+
|
|
191
|
+
**Update subsystem `structure.md` when:**
|
|
192
|
+
- Top-level directory added, renamed, or removed within the subsystem
|
|
193
|
+
|
|
194
|
+
**Update subsystem `architecture.md` when:**
|
|
195
|
+
- New architectural layer or component type introduced
|
|
196
|
+
- New inbound or outbound dependency added
|
|
197
|
+
|
|
198
|
+
**Update knowledge docs when:**
|
|
199
|
+
- `systems/` — new component, behavior, entry point, or integration point
|
|
200
|
+
- `patterns/` — new implementation added, pattern structure changed
|
|
201
|
+
- `cross-cutting/` — new registration, mechanism changed
|
|
202
|
+
- `guides/` — new step required, step order changed, reference implementation changed
|
|
203
|
+
- `decisions/` — NEVER edit accepted ADRs; create a new one that supersedes
|
|
204
|
+
|
|
205
|
+
### Tech Debt
|
|
206
|
+
|
|
207
|
+
Tech debt items are tracked in individual `systems/` and `cross-cutting/` docs (## Tech Debt section)
|
|
208
|
+
and rolled up in `system-wide/tech-debt-index.md`. Items are removed when fixed.
|
|
209
|
+
</keeping-current>
|
|
210
|
+
|
|
211
|
+
<subsystem-index>
|
|
212
|
+
## Subsystems
|
|
213
|
+
|
|
214
|
+
[POPULATE FROM system-structure.md — list each subsystem with link to its wiki folder]
|
|
215
|
+
|
|
216
|
+
| Subsystem | Wiki Path | Responsibility |
|
|
217
|
+
|-----------|-----------|----------------|
|
|
218
|
+
| [name] | [subsystems/name/](subsystems/name/) | [one-line responsibility] |
|
|
219
|
+
</subsystem-index>
|
|
220
|
+
</template>
|
|
221
|
+
|
|
222
|
+
<guidelines>
|
|
223
|
+
|
|
224
|
+
**This is a META-DOCUMENT, not a code documentation template.**
|
|
225
|
+
It describes the wiki system itself — its structure, conventions, and usage.
|
|
226
|
+
It does NOT contain code references, mermaid diagrams, or architectural content.
|
|
227
|
+
|
|
228
|
+
**Populating the template:**
|
|
229
|
+
- The Directory Structure section is FIXED — it describes the standard wiki layout.
|
|
230
|
+
Do NOT customize it per project. It shows the canonical structure.
|
|
231
|
+
- The Document Types tables are FIXED — they describe what each document type is.
|
|
232
|
+
- The Subsystems table at the bottom MUST be populated from `system-structure.md`
|
|
233
|
+
(the subsystem index). If `system-structure.md` doesn't exist yet, leave the table
|
|
234
|
+
with placeholder rows and a note to populate after `/ace:map-system`.
|
|
235
|
+
- All wiki paths in the Subsystems table should be relative links from the wiki root.
|
|
236
|
+
|
|
237
|
+
**Tone:**
|
|
238
|
+
- Direct and practical — this is a reference, not a tutorial
|
|
239
|
+
- Written for two audiences in parallel: humans and AI agents
|
|
240
|
+
- Short sentences, bullet points, tables over prose
|
|
241
|
+
- No filler, no motivational text, no history
|
|
242
|
+
|
|
243
|
+
**What does NOT belong here:**
|
|
244
|
+
- Actual code documentation (that lives in the wiki docs themselves)
|
|
245
|
+
- Project-specific architecture details (that's system-architecture.md)
|
|
246
|
+
- Process details about ACE workflows (that's internal to the tool)
|
|
247
|
+
- Story or feature information
|
|
248
|
+
- Revision history
|
|
249
|
+
|
|
250
|
+
</guidelines>
|
|
251
|
+
|
|
252
|
+
<evolution>
|
|
253
|
+
|
|
254
|
+
This document is MOSTLY STABLE — it describes the wiki system, which rarely changes.
|
|
255
|
+
|
|
256
|
+
**Update triggers:**
|
|
257
|
+
- New document type added to the wiki system (e.g., a new knowledge category)
|
|
258
|
+
- New subsystem mapped (update the Subsystems table)
|
|
259
|
+
- Subsystem removed or renamed (update the Subsystems table)
|
|
260
|
+
- Wiki conventions changed (naming rules, diagram rules, reference format)
|
|
261
|
+
|
|
262
|
+
**NOT an update trigger:**
|
|
263
|
+
- New documents created within existing categories
|
|
264
|
+
- Content updates to any wiki document
|
|
265
|
+
- New stories, features, or sprints
|
|
266
|
+
- Changes to ACE tool internals
|
|
267
|
+
|
|
268
|
+
**Update rules:**
|
|
269
|
+
- UPDATE the Subsystems table when subsystems are added/removed
|
|
270
|
+
- The rest of the document should rarely need changes
|
|
271
|
+
- If the wiki structure itself evolves (new folders, new doc types), update the
|
|
272
|
+
Directory Structure and Document Types sections
|
|
273
|
+
|
|
274
|
+
</evolution>
|
|
275
|
+
|
|
276
|
+
</wiki-readme>
|
|
@@ -175,6 +175,24 @@
|
|
|
175
175
|
mkdir -p .docs/wiki/system-wide
|
|
176
176
|
```
|
|
177
177
|
|
|
178
|
+
**Generate wiki-readme.md if it does not already exist:**
|
|
179
|
+
|
|
180
|
+
Check if `.docs/wiki/wiki-readme.md` exists. If it does NOT exist, generate it
|
|
181
|
+
from the wiki-readme template (`~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml`).
|
|
182
|
+
|
|
183
|
+
Read the template's `<template>` section and write the markdown content to
|
|
184
|
+
`.docs/wiki/wiki-readme.md`. This is a mostly-static meta-document — fill it
|
|
185
|
+
directly without spawning an agent:
|
|
186
|
+
- Directory Structure section: use as-is from template (canonical layout)
|
|
187
|
+
- Document Types tables: use as-is from template
|
|
188
|
+
- How to Use sections: use as-is from template
|
|
189
|
+
- Creating New Documents section: use as-is from template
|
|
190
|
+
- Keeping Current section: use as-is from template
|
|
191
|
+
- Subsystems table: leave with placeholder rows — will be populated when
|
|
192
|
+
`/ace:map-subsystem` runs
|
|
193
|
+
|
|
194
|
+
If `.docs/wiki/wiki-readme.md` already exists, skip — do not overwrite.
|
|
195
|
+
|
|
178
196
|
Continue to step 4.
|
|
179
197
|
</step>
|
|
180
198
|
|
|
@@ -581,6 +599,11 @@
|
|
|
581
599
|
git add .docs/wiki/system-wide/
|
|
582
600
|
```
|
|
583
601
|
|
|
602
|
+
If wiki-readme.md was created in step 3:
|
|
603
|
+
```bash
|
|
604
|
+
git add .docs/wiki/wiki-readme.md
|
|
605
|
+
```
|
|
606
|
+
|
|
584
607
|
If CLAUDE.md was created or updated:
|
|
585
608
|
```bash
|
|
586
609
|
git add CLAUDE.md
|
|
@@ -608,6 +631,7 @@
|
|
|
608
631
|
Documents:
|
|
609
632
|
──────────
|
|
610
633
|
[For each document, show action taken and line count]
|
|
634
|
+
+ wiki-readme.md ([N] lines) — [created | already exists]
|
|
611
635
|
+ system-structure.md ([N] lines) — [created/updated/recreated/scaffolded]
|
|
612
636
|
+ testing-framework.md ([N] lines) — [created/updated/recreated/scaffolded]
|
|
613
637
|
+ system-architecture.md ([N] lines) — [created/updated/recreated/scaffolded]
|
|
@@ -633,6 +657,7 @@
|
|
|
633
657
|
|
|
634
658
|
<success_criteria>
|
|
635
659
|
- Init function executed (brownfield/greenfield detected, document existence checked)
|
|
660
|
+
- wiki-readme.md created at .docs/wiki/wiki-readme.md if it did not already exist
|
|
636
661
|
- Each document triaged independently (create/update/recreate/scaffold/skip)
|
|
637
662
|
- Greenfield: structure and testing scaffolded, architecture created via interview
|
|
638
663
|
- Brownfield: all documents created/updated by ace-wiki-mapper agents
|
|
@@ -640,7 +665,7 @@
|
|
|
640
665
|
- CLAUDE.md updated with wiki maintenance instructions
|
|
641
666
|
- All created documents verified for content (non-empty, non-placeholder for brownfield)
|
|
642
667
|
- Security scan passed (no secrets in generated docs)
|
|
643
|
-
- Documents committed to .docs/wiki/system-wide/
|
|
668
|
+
- Documents committed to .docs/wiki/system-wide/ (and .docs/wiki/wiki-readme.md)
|
|
644
669
|
- User sees clear completion summary and next steps
|
|
645
670
|
</success_criteria>
|
|
646
671
|
|
|
@@ -51,6 +51,7 @@ allowed-tools:
|
|
|
51
51
|
<system-structure-template>@~/.claude/agile-context-engineering/templates/wiki/system-structure.xml</system-structure-template>
|
|
52
52
|
<system-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml</system-architecture-template>
|
|
53
53
|
<testing-framework-template>@~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml</testing-framework-template>
|
|
54
|
+
<wiki-readme-template>@~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml</wiki-readme-template>
|
|
54
55
|
<questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
|
|
55
56
|
<ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
|
|
56
57
|
</execution-context>
|
|
@@ -65,6 +66,7 @@ allowed-tools:
|
|
|
65
66
|
</objective>
|
|
66
67
|
|
|
67
68
|
<artifacts>
|
|
69
|
+
- .docs/wiki/wiki-readme.md (created if not already present)
|
|
68
70
|
- .docs/wiki/system-wide/system-structure.md
|
|
69
71
|
- .docs/wiki/system-wide/system-architecture.md
|
|
70
72
|
- .docs/wiki/system-wide/testing-framework.md
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agile-context-engineering",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "ACE - Agile Context Engineering: A spec-driven development system for Claude Code and Crush (formerly OpenCode) with Agile workflows",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"bin": {
|