plan-flow-skill 1.0.0 → 1.0.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.
- package/.claude/rules/core/project-ledger.md +150 -0
- package/dist/cli/commands/init.js +2 -2
- package/dist/cli/commands/init.js.map +1 -1
- package/dist/cli/handlers/shared.d.ts +3 -3
- package/dist/cli/handlers/shared.d.ts.map +1 -1
- package/dist/cli/handlers/shared.js +86 -4
- package/dist/cli/handlers/shared.js.map +1 -1
- package/package.json +1 -1
- package/rules/core/_index.mdc +12 -2
- package/rules/core/project-ledger.mdc +155 -0
- package/skills/plan-flow/SKILL.md +9 -2
- package/skills/plan-flow/ledger/SKILL.md +70 -0
- package/templates/shared/AGENTS.md.template +6 -1
- package/templates/shared/CLAUDE.md.template +7 -2
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Project Ledger
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
|
|
5
|
+
A persistent, project-specific learning journal maintained across sessions. The ledger captures mistakes, corrections, discovered patterns, and hard-won knowledge about a specific codebase - building institutional memory that compounds over time.
|
|
6
|
+
|
|
7
|
+
**Location**: `flow/ledger.md`
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Behavior
|
|
12
|
+
|
|
13
|
+
### On Session Start
|
|
14
|
+
|
|
15
|
+
1. Check if `flow/ledger.md` exists
|
|
16
|
+
2. If it exists, read it and internalize the learnings silently
|
|
17
|
+
3. If it doesn't exist and the `flow/` directory exists, create it using the template below
|
|
18
|
+
4. Apply all recorded learnings naturally - never announce "I read the ledger" or reference it unless asked
|
|
19
|
+
|
|
20
|
+
### During Work
|
|
21
|
+
|
|
22
|
+
Record entries as soon as you learn something worth remembering. Don't batch updates for the end of a session - write them while the context is fresh.
|
|
23
|
+
|
|
24
|
+
**Update the ledger when you:**
|
|
25
|
+
|
|
26
|
+
- Get corrected by the user on something project-specific
|
|
27
|
+
- Discover an undocumented project quirk or constraint
|
|
28
|
+
- Find that an approach doesn't work in this codebase (and why)
|
|
29
|
+
- Learn a user preference for how they like things done
|
|
30
|
+
- Successfully navigate a tricky problem unique to this project
|
|
31
|
+
- Notice a gap between documented patterns and actual codebase behavior
|
|
32
|
+
- Encounter environment-specific gotchas (build issues, tool configs, etc.)
|
|
33
|
+
- Learn domain-specific terminology or business rules
|
|
34
|
+
|
|
35
|
+
### What NOT to Record
|
|
36
|
+
|
|
37
|
+
- Generic programming knowledge (that's what rules files are for)
|
|
38
|
+
- Patterns already documented in `.claude/rules/` files
|
|
39
|
+
- Temporary issues that won't recur
|
|
40
|
+
- Information that belongs in a discovery document or plan
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Entry Format
|
|
45
|
+
|
|
46
|
+
Each entry should be concise and actionable. Write entries as lessons, not as narratives.
|
|
47
|
+
|
|
48
|
+
**Good entries:**
|
|
49
|
+
- "The `buildWidgets` script requires Node 18+ - fails silently on Node 16"
|
|
50
|
+
- "User prefers explicit error types over generic Error class"
|
|
51
|
+
- "API responses from /legacy/* endpoints use snake_case despite the rest being camelCase"
|
|
52
|
+
- "Tests for streaming endpoints need a 3s timeout override - default 5s causes CI flakiness"
|
|
53
|
+
|
|
54
|
+
**Bad entries:**
|
|
55
|
+
- "Had a good session today" (not actionable)
|
|
56
|
+
- "JavaScript uses === for strict equality" (generic knowledge)
|
|
57
|
+
- "Fixed a bug in user service" (too vague, no lesson)
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Ledger Sections
|
|
62
|
+
|
|
63
|
+
### Project Quirks
|
|
64
|
+
|
|
65
|
+
Things that are unique or surprising about this specific project. Build config gotchas, undocumented dependencies between modules, services that behave differently than expected.
|
|
66
|
+
|
|
67
|
+
### What Works
|
|
68
|
+
|
|
69
|
+
Approaches and solutions that proved effective in this project. Patterns that solved recurring problems. Techniques the user approved of.
|
|
70
|
+
|
|
71
|
+
### What Didn't Work
|
|
72
|
+
|
|
73
|
+
Approaches that were tried and failed, with brief explanation of why. This prevents repeating the same mistakes across sessions.
|
|
74
|
+
|
|
75
|
+
### User Preferences
|
|
76
|
+
|
|
77
|
+
How the user likes things done. Communication style, code style preferences beyond what's in rules files, workflow preferences, conventions they care about.
|
|
78
|
+
|
|
79
|
+
### Domain Context
|
|
80
|
+
|
|
81
|
+
Business logic, domain terminology, and project-specific concepts that affect technical decisions. Things that aren't obvious from reading the code alone.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Template
|
|
86
|
+
|
|
87
|
+
When creating `flow/ledger.md` for the first time, use this structure:
|
|
88
|
+
|
|
89
|
+
```markdown
|
|
90
|
+
# Project Ledger
|
|
91
|
+
|
|
92
|
+
> Persistent learning journal - updated automatically across sessions.
|
|
93
|
+
> Last updated: {date}
|
|
94
|
+
|
|
95
|
+
## Project Quirks
|
|
96
|
+
|
|
97
|
+
<!-- Unexpected behaviors, environment gotchas, undocumented constraints -->
|
|
98
|
+
|
|
99
|
+
## What Works
|
|
100
|
+
|
|
101
|
+
<!-- Proven approaches and solutions for this project -->
|
|
102
|
+
|
|
103
|
+
## What Didn't Work
|
|
104
|
+
|
|
105
|
+
<!-- Failed approaches with brief "why" so we don't repeat them -->
|
|
106
|
+
|
|
107
|
+
## User Preferences
|
|
108
|
+
|
|
109
|
+
<!-- How the user likes things done beyond what rules files capture -->
|
|
110
|
+
|
|
111
|
+
## Domain Context
|
|
112
|
+
|
|
113
|
+
<!-- Business logic, terminology, and concepts that affect decisions -->
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Maintenance Rules
|
|
119
|
+
|
|
120
|
+
1. **Keep it under 150 lines** of high-signal content
|
|
121
|
+
2. **Consolidate periodically**: After every 8-10 sessions, merge similar entries, remove outdated ones, and promote recurring corrections to standing guidelines
|
|
122
|
+
3. **Remove stale entries**: If a quirk gets fixed or a constraint is lifted, remove the entry
|
|
123
|
+
4. **Promote to rules**: If a preference or pattern becomes well-established, move it to the appropriate rules file and remove from the ledger
|
|
124
|
+
5. **No duplicates**: Before adding an entry, scan existing entries to avoid redundancy
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Integration with Plan-Flow Workflow
|
|
129
|
+
|
|
130
|
+
The ledger naturally captures learnings from plan-flow activities:
|
|
131
|
+
|
|
132
|
+
| Activity | What Gets Captured |
|
|
133
|
+
|----------|-------------------|
|
|
134
|
+
| `/setup` | Environment surprises, toolchain quirks |
|
|
135
|
+
| `/discovery-plan` | Domain context, business rules learned from user |
|
|
136
|
+
| `/execute-plan` | What worked/didn't during implementation |
|
|
137
|
+
| `/review-code` | Pattern conflicts discovered, user feedback on style |
|
|
138
|
+
| `/review-pr` | Recurring review issues, team conventions |
|
|
139
|
+
|
|
140
|
+
The ledger is **not** a replacement for plan-flow artifacts. Discovery documents, plans, and reviews remain in their respective folders. The ledger captures the meta-learnings that span across activities.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Rules
|
|
145
|
+
|
|
146
|
+
1. **Silent by default**: Never tell the user "I updated the ledger" unless they ask about it
|
|
147
|
+
2. **Immediate writes**: Record learnings as they happen, don't wait
|
|
148
|
+
3. **Lessons over logs**: Write what you learned, not what you did
|
|
149
|
+
4. **Project-specific only**: Only record things unique to this project
|
|
150
|
+
5. **Honest self-correction**: Record your own mistakes, not just user corrections
|
|
@@ -128,9 +128,9 @@ export async function runInit(options) {
|
|
|
128
128
|
}
|
|
129
129
|
results.push({ platform, result });
|
|
130
130
|
}
|
|
131
|
-
// Run shared handler (flow directories,
|
|
131
|
+
// Run shared handler (flow directories, .gitignore)
|
|
132
132
|
log.header('Setting up shared resources...');
|
|
133
|
-
const sharedResult = await initShared(target, { force });
|
|
133
|
+
const sharedResult = await initShared(target, { force }, platforms);
|
|
134
134
|
results.push({ platform: 'shared', result: sharedResult });
|
|
135
135
|
// Print summary and next steps
|
|
136
136
|
printSummary(results, target);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,SAAS,WAAW;IAClB,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC9B,GAAG,CAAC,IAAI,CACN,6GAA6G,CAC9G,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,OAAoB;IAC3C,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,OAAO,CAAC,MAAM;QAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,CAAC,MAAM;QAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,CAAC,QAAQ;QAAE,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACjD,IAAI,OAAO,CAAC,KAAK;QAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE3C,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC;AAED,SAAS,cAAc,CAAC,MAAc;IACpC,sCAAsC;IACtC,MAAM,UAAU,GAAG;QACjB,cAAc;QACd,gBAAgB;QAChB,YAAY;QACZ,QAAQ;QACR,SAAS;QACT,MAAM;KACP,CAAC;IAEF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAErE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,GAAG,CAAC,IAAI,CACN,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,CAAC,8BAA8B;AAC7C,CAAC;AAED,SAAS,YAAY,CAAC,OAAqB,EAAE,MAAc;IACzD,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAEtB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QACtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAEtC,YAAY,IAAI,OAAO,CAAC;QACxB,YAAY,IAAI,OAAO,CAAC;QACxB,YAAY,IAAI,OAAO,CAAC;QAExB,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,GAAG,CAAC,OAAO,CAAC,GAAG,QAAQ,KAAK,OAAO,kBAAkB,CAAC,CAAC;QACzD,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,KAAK,OAAO,kBAAkB,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,KAAK,OAAO,kCAAkC,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IAED,GAAG,CAAC,KAAK,EAAE,CAAC;IAEZ,IAAI,YAAY,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC;QACpC,GAAG,CAAC,OAAO,CACT,SAAS,YAAY,aAAa,YAAY,aAAa,YAAY,WAAW,CACnF,CAAC;IACJ,CAAC;SAAM,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC5B,GAAG,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,SAAqB;IAC3C,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEzB,IAAI,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,CACN,uEAAuE,CACxE,CAAC;IACJ,CAAC;IAED,IAAI,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,CAAC,0DAA0D,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,GAAG,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,GAAG,CAAC,IAAI,CACN,oFAAoF,CACrF,CAAC;IACJ,CAAC;IAED,GAAG,CAAC,KAAK,EAAE,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,OAAoB;IAChD,WAAW,EAAE,CAAC;IAEd,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IAErC,cAAc,CAAC,MAAM,CAAC,CAAC;IAEvB,sDAAsD;IACtD,IAAI,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,MAAM,eAAe,EAAE,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,KAAK,EAAE,CAAC;IACZ,GAAG,CAAC,IAAI,CAAC,mBAAmB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,GAAG,CAAC,IAAI,CAAC,WAAW,MAAM,EAAE,CAAC,CAAC;IAC9B,IAAI,KAAK,EAAE,CAAC;QACV,GAAG,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,iCAAiC;IACjC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,GAAG,CAAC,MAAM,CAAC,cAAc,QAAQ,KAAK,CAAC,CAAC;QAExC,IAAI,MAAM,CAAC;QACX,QAAQ,QAAQ,EAAE,CAAC;YACjB,KAAK,QAAQ;gBACX,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC7C,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC7C,MAAM;YACR,KAAK,UAAU;gBACb,MAAM,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC/C,MAAM;YACR,KAAK,OAAO;gBACV,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC5C,MAAM;QACV,CAAC;QAED,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED,oDAAoD;IACpD,GAAG,CAAC,MAAM,CAAC,gCAAgC,CAAC,CAAC;IAC7C,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IAE3D,+BAA+B;IAC/B,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9B,cAAc,CAAC,SAAS,CAAC,CAAC;AAC5B,CAAC"}
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Shared handler
|
|
3
3
|
*
|
|
4
|
-
* Creates flow/ directory structure.
|
|
4
|
+
* Creates flow/ directory structure and manages .gitignore entries.
|
|
5
5
|
* Runs for all platform installations.
|
|
6
6
|
*/
|
|
7
|
-
import type { CopyOptions, CopyResult } from '../types.js';
|
|
8
|
-
export declare function initShared(target: string,
|
|
7
|
+
import type { CopyOptions, CopyResult, Platform } from '../types.js';
|
|
8
|
+
export declare function initShared(target: string, options: CopyOptions, platforms?: Platform[]): Promise<CopyResult>;
|
|
9
9
|
//# sourceMappingURL=shared.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/cli/handlers/shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AA4GrE,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,SAAS,GAAE,QAAQ,EAAO,GACzB,OAAO,CAAC,UAAU,CAAC,CA+BrB"}
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Shared handler
|
|
3
3
|
*
|
|
4
|
-
* Creates flow/ directory structure.
|
|
4
|
+
* Creates flow/ directory structure and manages .gitignore entries.
|
|
5
5
|
* Runs for all platform installations.
|
|
6
6
|
*/
|
|
7
7
|
import { join } from 'node:path';
|
|
8
|
-
import { existsSync, writeFileSync } from 'node:fs';
|
|
8
|
+
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
|
|
9
9
|
import { ensureDir } from '../utils/files.js';
|
|
10
10
|
import * as log from '../utils/logger.js';
|
|
11
11
|
const FLOW_SUBDIRS = [
|
|
@@ -17,9 +17,86 @@ const FLOW_SUBDIRS = [
|
|
|
17
17
|
'reviewed-code',
|
|
18
18
|
'reviewed-pr',
|
|
19
19
|
];
|
|
20
|
-
|
|
20
|
+
const MARKER_START = '# >>> plan-flow';
|
|
21
|
+
const MARKER_END = '# <<< plan-flow';
|
|
22
|
+
/**
|
|
23
|
+
* Maps each platform to the paths it installs in the user's project.
|
|
24
|
+
*/
|
|
25
|
+
const PLATFORM_GITIGNORE_ENTRIES = {
|
|
26
|
+
claude: ['.claude/commands/', '.claude/rules/'],
|
|
27
|
+
cursor: ['rules/'],
|
|
28
|
+
openclaw: ['skills/plan-flow/'],
|
|
29
|
+
codex: ['.agents/skills/plan-flow/'],
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* Paths that should always be gitignored regardless of platform.
|
|
33
|
+
*/
|
|
34
|
+
const SHARED_GITIGNORE_ENTRIES = ['flow/', '.plan-flow.yml', '.plan.flow.env'];
|
|
35
|
+
/**
|
|
36
|
+
* Builds the plan-flow .gitignore block with markers.
|
|
37
|
+
*/
|
|
38
|
+
function buildGitignoreBlock(platforms) {
|
|
39
|
+
const lines = [MARKER_START];
|
|
40
|
+
// Shared entries
|
|
41
|
+
for (const entry of SHARED_GITIGNORE_ENTRIES) {
|
|
42
|
+
lines.push(entry);
|
|
43
|
+
}
|
|
44
|
+
// Platform-specific entries
|
|
45
|
+
for (const platform of platforms) {
|
|
46
|
+
const entries = PLATFORM_GITIGNORE_ENTRIES[platform];
|
|
47
|
+
if (entries) {
|
|
48
|
+
for (const entry of entries) {
|
|
49
|
+
lines.push(entry);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
lines.push(MARKER_END);
|
|
54
|
+
return lines.join('\n');
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Updates or creates .gitignore with plan-flow entries.
|
|
58
|
+
*/
|
|
59
|
+
function updateGitignore(target, platforms, options) {
|
|
60
|
+
const result = { created: [], skipped: [], updated: [] };
|
|
61
|
+
const gitignorePath = join(target, '.gitignore');
|
|
62
|
+
const block = buildGitignoreBlock(platforms);
|
|
63
|
+
if (!existsSync(gitignorePath)) {
|
|
64
|
+
// No .gitignore exists - create it with plan-flow entries
|
|
65
|
+
writeFileSync(gitignorePath, block + '\n', 'utf-8');
|
|
66
|
+
result.created.push(gitignorePath);
|
|
67
|
+
log.success('Created .gitignore with plan-flow entries');
|
|
68
|
+
return result;
|
|
69
|
+
}
|
|
70
|
+
const existing = readFileSync(gitignorePath, 'utf-8');
|
|
71
|
+
if (existing.includes(MARKER_START)) {
|
|
72
|
+
if (options.force) {
|
|
73
|
+
// Replace existing plan-flow section
|
|
74
|
+
const pattern = new RegExp(`${escapeRegExp(MARKER_START)}[\\s\\S]*?${escapeRegExp(MARKER_END)}`);
|
|
75
|
+
const updated = existing.replace(pattern, block);
|
|
76
|
+
writeFileSync(gitignorePath, updated, 'utf-8');
|
|
77
|
+
result.updated.push(gitignorePath);
|
|
78
|
+
log.warn('Updated plan-flow entries in .gitignore');
|
|
79
|
+
}
|
|
80
|
+
else {
|
|
81
|
+
result.skipped.push(gitignorePath);
|
|
82
|
+
log.skip('.gitignore already has plan-flow entries');
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
else {
|
|
86
|
+
// Append plan-flow section to existing .gitignore
|
|
87
|
+
const appended = existing.trimEnd() + '\n\n' + block + '\n';
|
|
88
|
+
writeFileSync(gitignorePath, appended, 'utf-8');
|
|
89
|
+
result.updated.push(gitignorePath);
|
|
90
|
+
log.success('Added plan-flow entries to .gitignore');
|
|
91
|
+
}
|
|
92
|
+
return result;
|
|
93
|
+
}
|
|
94
|
+
function escapeRegExp(str) {
|
|
95
|
+
return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
96
|
+
}
|
|
97
|
+
export async function initShared(target, options, platforms = []) {
|
|
21
98
|
const result = { created: [], skipped: [], updated: [] };
|
|
22
|
-
// Create flow/ directory structure with .gitkeep files
|
|
99
|
+
// 1. Create flow/ directory structure with .gitkeep files
|
|
23
100
|
const flowDir = join(target, 'flow');
|
|
24
101
|
for (const subdir of FLOW_SUBDIRS) {
|
|
25
102
|
const dir = join(flowDir, subdir);
|
|
@@ -39,6 +116,11 @@ export async function initShared(target, _options) {
|
|
|
39
116
|
log.skip(`flow/${subdir}/ already exists`);
|
|
40
117
|
}
|
|
41
118
|
}
|
|
119
|
+
// 2. Update .gitignore with plan-flow entries
|
|
120
|
+
const giResult = updateGitignore(target, platforms, options);
|
|
121
|
+
result.created.push(...giResult.created);
|
|
122
|
+
result.skipped.push(...giResult.skipped);
|
|
123
|
+
result.updated.push(...giResult.updated);
|
|
42
124
|
return result;
|
|
43
125
|
}
|
|
44
126
|
//# sourceMappingURL=shared.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/cli/handlers/shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/cli/handlers/shared.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
package/rules/core/_index.mdc
CHANGED
|
@@ -9,8 +9,8 @@ alwaysApply: false
|
|
|
9
9
|
|
|
10
10
|
Core rules define the foundational coding standards that apply across the entire project. These include best practices to follow (allowed patterns), anti-patterns to avoid (forbidden patterns), and complexity scoring for implementation planning.
|
|
11
11
|
|
|
12
|
-
**Total Files**:
|
|
13
|
-
**Reference Codes**: COR-AP-1 through COR-
|
|
12
|
+
**Total Files**: 4 files, ~833 lines
|
|
13
|
+
**Reference Codes**: COR-AP-1 through COR-LDG-2
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -40,6 +40,13 @@ Core rules define the foundational coding standards that apply across the entire
|
|
|
40
40
|
| COR-CS-4 | Common complexity patterns table | complexity-scoring.mdc | 168-185 |
|
|
41
41
|
| COR-CS-5 | Real-world scoring examples | complexity-scoring.mdc | 187-236 |
|
|
42
42
|
|
|
43
|
+
### Project Ledger (`project-ledger.mdc`)
|
|
44
|
+
|
|
45
|
+
| Code | Description | Source | Lines |
|
|
46
|
+
|------|-------------|--------|-------|
|
|
47
|
+
| COR-LDG-1 | Ledger behavior, entry format, and sections | project-ledger.mdc | 10-110 |
|
|
48
|
+
| COR-LDG-2 | Maintenance rules and plan-flow integration | project-ledger.mdc | 112-155 |
|
|
49
|
+
|
|
43
50
|
---
|
|
44
51
|
|
|
45
52
|
## When to Expand
|
|
@@ -55,6 +62,8 @@ Core rules define the foundational coding standards that apply across the entire
|
|
|
55
62
|
| COR-CS-3 | Determining execution strategy for plan phases |
|
|
56
63
|
| COR-CS-4 | Quick lookup of typical complexity scores |
|
|
57
64
|
| COR-CS-5 | Need detailed scoring examples |
|
|
65
|
+
| COR-LDG-1 | Need ledger behavior and entry guidelines |
|
|
66
|
+
| COR-LDG-2 | Need ledger maintenance and integration rules |
|
|
58
67
|
|
|
59
68
|
---
|
|
60
69
|
|
|
@@ -86,4 +95,5 @@ Core rules define the foundational coding standards that apply across the entire
|
|
|
86
95
|
## Notes
|
|
87
96
|
|
|
88
97
|
- `allowed-patterns.mdc` and `forbidden-patterns.mdc` have `alwaysApply: true` - they are loaded automatically by Cursor
|
|
98
|
+
- `project-ledger.mdc` has `alwaysApply: true` - maintains persistent project memory
|
|
89
99
|
- `complexity-scoring.mdc` is loaded on-demand when needed for planning
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: "Persistent project learning journal - always active to maintain institutional memory across sessions"
|
|
3
|
+
alwaysApply: true
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Project Ledger
|
|
7
|
+
|
|
8
|
+
## Purpose
|
|
9
|
+
|
|
10
|
+
A persistent, project-specific learning journal maintained across sessions. The ledger captures mistakes, corrections, discovered patterns, and hard-won knowledge about a specific codebase - building institutional memory that compounds over time.
|
|
11
|
+
|
|
12
|
+
**Location**: `flow/ledger.md`
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Behavior
|
|
17
|
+
|
|
18
|
+
### On Session Start
|
|
19
|
+
|
|
20
|
+
1. Check if `flow/ledger.md` exists
|
|
21
|
+
2. If it exists, read it and internalize the learnings silently
|
|
22
|
+
3. If it doesn't exist and the `flow/` directory exists, create it using the template below
|
|
23
|
+
4. Apply all recorded learnings naturally - never announce "I read the ledger" or reference it unless asked
|
|
24
|
+
|
|
25
|
+
### During Work
|
|
26
|
+
|
|
27
|
+
Record entries as soon as you learn something worth remembering. Don't batch updates for the end of a session - write them while the context is fresh.
|
|
28
|
+
|
|
29
|
+
**Update the ledger when you:**
|
|
30
|
+
|
|
31
|
+
- Get corrected by the user on something project-specific
|
|
32
|
+
- Discover an undocumented project quirk or constraint
|
|
33
|
+
- Find that an approach doesn't work in this codebase (and why)
|
|
34
|
+
- Learn a user preference for how they like things done
|
|
35
|
+
- Successfully navigate a tricky problem unique to this project
|
|
36
|
+
- Notice a gap between documented patterns and actual codebase behavior
|
|
37
|
+
- Encounter environment-specific gotchas (build issues, tool configs, etc.)
|
|
38
|
+
- Learn domain-specific terminology or business rules
|
|
39
|
+
|
|
40
|
+
### What NOT to Record
|
|
41
|
+
|
|
42
|
+
- Generic programming knowledge (that's what rules files are for)
|
|
43
|
+
- Patterns already documented in rules files
|
|
44
|
+
- Temporary issues that won't recur
|
|
45
|
+
- Information that belongs in a discovery document or plan
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Entry Format
|
|
50
|
+
|
|
51
|
+
Each entry should be concise and actionable. Write entries as lessons, not as narratives.
|
|
52
|
+
|
|
53
|
+
**Good entries:**
|
|
54
|
+
- "The `buildWidgets` script requires Node 18+ - fails silently on Node 16"
|
|
55
|
+
- "User prefers explicit error types over generic Error class"
|
|
56
|
+
- "API responses from /legacy/* endpoints use snake_case despite the rest being camelCase"
|
|
57
|
+
- "Tests for streaming endpoints need a 3s timeout override - default 5s causes CI flakiness"
|
|
58
|
+
|
|
59
|
+
**Bad entries:**
|
|
60
|
+
- "Had a good session today" (not actionable)
|
|
61
|
+
- "JavaScript uses === for strict equality" (generic knowledge)
|
|
62
|
+
- "Fixed a bug in user service" (too vague, no lesson)
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Ledger Sections
|
|
67
|
+
|
|
68
|
+
### Project Quirks
|
|
69
|
+
|
|
70
|
+
Things that are unique or surprising about this specific project. Build config gotchas, undocumented dependencies between modules, services that behave differently than expected.
|
|
71
|
+
|
|
72
|
+
### What Works
|
|
73
|
+
|
|
74
|
+
Approaches and solutions that proved effective in this project. Patterns that solved recurring problems. Techniques the user approved of.
|
|
75
|
+
|
|
76
|
+
### What Didn't Work
|
|
77
|
+
|
|
78
|
+
Approaches that were tried and failed, with brief explanation of why. This prevents repeating the same mistakes across sessions.
|
|
79
|
+
|
|
80
|
+
### User Preferences
|
|
81
|
+
|
|
82
|
+
How the user likes things done. Communication style, code style preferences beyond what's in rules files, workflow preferences, conventions they care about.
|
|
83
|
+
|
|
84
|
+
### Domain Context
|
|
85
|
+
|
|
86
|
+
Business logic, domain terminology, and project-specific concepts that affect technical decisions. Things that aren't obvious from reading the code alone.
|
|
87
|
+
|
|
88
|
+
---
|
|
89
|
+
|
|
90
|
+
## Template
|
|
91
|
+
|
|
92
|
+
When creating `flow/ledger.md` for the first time, use this structure:
|
|
93
|
+
|
|
94
|
+
```markdown
|
|
95
|
+
# Project Ledger
|
|
96
|
+
|
|
97
|
+
> Persistent learning journal - updated automatically across sessions.
|
|
98
|
+
> Last updated: {date}
|
|
99
|
+
|
|
100
|
+
## Project Quirks
|
|
101
|
+
|
|
102
|
+
<!-- Unexpected behaviors, environment gotchas, undocumented constraints -->
|
|
103
|
+
|
|
104
|
+
## What Works
|
|
105
|
+
|
|
106
|
+
<!-- Proven approaches and solutions for this project -->
|
|
107
|
+
|
|
108
|
+
## What Didn't Work
|
|
109
|
+
|
|
110
|
+
<!-- Failed approaches with brief "why" so we don't repeat them -->
|
|
111
|
+
|
|
112
|
+
## User Preferences
|
|
113
|
+
|
|
114
|
+
<!-- How the user likes things done beyond what rules files capture -->
|
|
115
|
+
|
|
116
|
+
## Domain Context
|
|
117
|
+
|
|
118
|
+
<!-- Business logic, terminology, and concepts that affect decisions -->
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Maintenance Rules
|
|
124
|
+
|
|
125
|
+
1. **Keep it under 150 lines** of high-signal content
|
|
126
|
+
2. **Consolidate periodically**: After every 8-10 sessions, merge similar entries, remove outdated ones, and promote recurring corrections to standing guidelines
|
|
127
|
+
3. **Remove stale entries**: If a quirk gets fixed or a constraint is lifted, remove the entry
|
|
128
|
+
4. **Promote to rules**: If a preference or pattern becomes well-established, move it to the appropriate rules file and remove from the ledger
|
|
129
|
+
5. **No duplicates**: Before adding an entry, scan existing entries to avoid redundancy
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## Integration with Plan-Flow Workflow
|
|
134
|
+
|
|
135
|
+
The ledger naturally captures learnings from plan-flow activities:
|
|
136
|
+
|
|
137
|
+
| Activity | What Gets Captured |
|
|
138
|
+
|----------|-------------------|
|
|
139
|
+
| `/setup` | Environment surprises, toolchain quirks |
|
|
140
|
+
| `/discovery-plan` | Domain context, business rules learned from user |
|
|
141
|
+
| `/execute-plan` | What worked/didn't during implementation |
|
|
142
|
+
| `/review-code` | Pattern conflicts discovered, user feedback on style |
|
|
143
|
+
| `/review-pr` | Recurring review issues, team conventions |
|
|
144
|
+
|
|
145
|
+
The ledger is **not** a replacement for plan-flow artifacts. Discovery documents, plans, and reviews remain in their respective folders. The ledger captures the meta-learnings that span across activities.
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Rules
|
|
150
|
+
|
|
151
|
+
1. **Silent by default**: Never tell the user "I updated the ledger" unless they ask about it
|
|
152
|
+
2. **Immediate writes**: Record learnings as they happen, don't wait
|
|
153
|
+
3. **Lessons over logs**: Write what you learned, not what you did
|
|
154
|
+
4. **Project-specific only**: Only record things unique to this project
|
|
155
|
+
5. **Honest self-correction**: Record your own mistakes, not just user corrections
|
|
@@ -8,7 +8,7 @@ user-invocable: true
|
|
|
8
8
|
|
|
9
9
|
# Plan-Flow: Structured AI-Assisted Development
|
|
10
10
|
|
|
11
|
-
A comprehensive skill set for AI-assisted software development with structured workflows.
|
|
11
|
+
A comprehensive skill set for AI-assisted software development with structured workflows and persistent project memory.
|
|
12
12
|
|
|
13
13
|
## Available Commands
|
|
14
14
|
|
|
@@ -23,6 +23,12 @@ A comprehensive skill set for AI-assisted software development with structured w
|
|
|
23
23
|
| `/review-pr` | Review a Pull Request |
|
|
24
24
|
| `/write-tests` | Write tests to achieve coverage target |
|
|
25
25
|
|
|
26
|
+
## Always-Active Features
|
|
27
|
+
|
|
28
|
+
| Feature | Description |
|
|
29
|
+
|---------|-------------|
|
|
30
|
+
| Project Ledger | Persistent learning journal at `flow/ledger.md` - silently captures mistakes, corrections, and project-specific knowledge across sessions |
|
|
31
|
+
|
|
26
32
|
## Recommended Workflow
|
|
27
33
|
|
|
28
34
|
**Automated - runs without asking permission:**
|
|
@@ -70,7 +76,8 @@ flow/
|
|
|
70
76
|
├── plans/ # Active implementation plans
|
|
71
77
|
├── references/ # Reference materials
|
|
72
78
|
├── reviewed-code/ # Code review documents
|
|
73
|
-
|
|
79
|
+
├── reviewed-pr/ # PR review documents
|
|
80
|
+
└── ledger.md # Persistent project learning journal
|
|
74
81
|
```
|
|
75
82
|
|
|
76
83
|
## Critical Rules
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ledger
|
|
3
|
+
description: Persistent project learning journal that builds institutional memory across sessions
|
|
4
|
+
metadata: {"openclaw":{"requires":{"bins":["git"]}}}
|
|
5
|
+
user-invocable: false
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Project Ledger
|
|
9
|
+
|
|
10
|
+
A persistent, project-specific learning journal maintained across sessions. Captures mistakes, corrections, discovered patterns, and hard-won knowledge about a specific codebase.
|
|
11
|
+
|
|
12
|
+
## How It Works
|
|
13
|
+
|
|
14
|
+
The ledger operates silently in the background:
|
|
15
|
+
|
|
16
|
+
1. **Session Start**: Read `flow/ledger.md` and apply learnings
|
|
17
|
+
2. **During Work**: Record new learnings as they happen
|
|
18
|
+
3. **Maintenance**: Periodically consolidate and prune entries
|
|
19
|
+
|
|
20
|
+
## File Location
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
flow/ledger.md
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## What Gets Recorded
|
|
27
|
+
|
|
28
|
+
- Project-specific quirks and gotchas
|
|
29
|
+
- Approaches that worked or didn't work
|
|
30
|
+
- User preferences beyond documented rules
|
|
31
|
+
- Domain context and business logic
|
|
32
|
+
- Environment and toolchain surprises
|
|
33
|
+
- Self-corrections and mistakes made
|
|
34
|
+
|
|
35
|
+
## What Doesn't Get Recorded
|
|
36
|
+
|
|
37
|
+
- Generic programming knowledge
|
|
38
|
+
- Patterns already in rules files
|
|
39
|
+
- Temporary one-off issues
|
|
40
|
+
- Content that belongs in discovery docs or plans
|
|
41
|
+
|
|
42
|
+
## Entry Style
|
|
43
|
+
|
|
44
|
+
Write lessons, not logs. Each entry should be concise and actionable.
|
|
45
|
+
|
|
46
|
+
**Examples:**
|
|
47
|
+
- "The `buildWidgets` script requires Node 18+ - fails silently on Node 16"
|
|
48
|
+
- "User prefers explicit error types over generic Error class"
|
|
49
|
+
- "Tests for streaming endpoints need a 3s timeout override"
|
|
50
|
+
|
|
51
|
+
## Sections
|
|
52
|
+
|
|
53
|
+
| Section | Purpose |
|
|
54
|
+
|---------|---------|
|
|
55
|
+
| Project Quirks | Surprising behaviors, undocumented constraints |
|
|
56
|
+
| What Works | Proven approaches for this project |
|
|
57
|
+
| What Didn't Work | Failed approaches with reasoning |
|
|
58
|
+
| User Preferences | How the user likes things done |
|
|
59
|
+
| Domain Context | Business logic and terminology |
|
|
60
|
+
|
|
61
|
+
## Maintenance
|
|
62
|
+
|
|
63
|
+
- Keep under 150 lines of high-signal content
|
|
64
|
+
- Consolidate every 8-10 sessions
|
|
65
|
+
- Remove stale entries when quirks get fixed
|
|
66
|
+
- Promote established patterns to rules files
|
|
67
|
+
|
|
68
|
+
## Integration
|
|
69
|
+
|
|
70
|
+
Learnings are naturally captured from all plan-flow activities (setup, discovery, execution, reviews). The ledger captures meta-learnings that span across individual artifacts.
|
|
@@ -21,6 +21,10 @@
|
|
|
21
21
|
4. `/execute-plan` - Execute the plan phase by phase
|
|
22
22
|
5. `/review-code` or `/review-pr` - Review changes before merging
|
|
23
23
|
|
|
24
|
+
## Project Ledger
|
|
25
|
+
|
|
26
|
+
The Project Ledger (`flow/ledger.md`) is always active. It silently captures project-specific learnings, mistakes, and corrections across sessions - building institutional memory that improves AI assistance over time.
|
|
27
|
+
|
|
24
28
|
## Critical Rules
|
|
25
29
|
|
|
26
30
|
1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user.
|
|
@@ -38,7 +42,8 @@ flow/
|
|
|
38
42
|
├── plans/ # Active implementation plans
|
|
39
43
|
├── references/ # Reference materials
|
|
40
44
|
├── reviewed-code/ # Code review documents
|
|
41
|
-
|
|
45
|
+
├── reviewed-pr/ # PR review documents
|
|
46
|
+
└── ledger.md # Persistent project learning journal
|
|
42
47
|
```
|
|
43
48
|
|
|
44
49
|
## Complexity Scoring
|
|
@@ -21,6 +21,10 @@
|
|
|
21
21
|
4. `/execute-plan` - Execute the plan phase by phase
|
|
22
22
|
5. `/review-code` or `/review-pr` - Review changes before merging
|
|
23
23
|
|
|
24
|
+
## Project Ledger
|
|
25
|
+
|
|
26
|
+
The Project Ledger (`flow/ledger.md`) is always active. It silently captures project-specific learnings, mistakes, and corrections across sessions - building institutional memory that improves AI assistance over time. See `.claude/rules/core/project-ledger.md` for details.
|
|
27
|
+
|
|
24
28
|
## Critical Rules
|
|
25
29
|
|
|
26
30
|
1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user.
|
|
@@ -38,7 +42,8 @@ flow/
|
|
|
38
42
|
├── plans/ # Active implementation plans
|
|
39
43
|
├── references/ # Reference materials
|
|
40
44
|
├── reviewed-code/ # Code review documents
|
|
41
|
-
|
|
45
|
+
├── reviewed-pr/ # PR review documents
|
|
46
|
+
└── ledger.md # Persistent project learning journal
|
|
42
47
|
```
|
|
43
48
|
|
|
44
49
|
## Complexity Scoring
|
|
@@ -56,7 +61,7 @@ Every plan phase has a complexity score (0-10):
|
|
|
56
61
|
## Rules
|
|
57
62
|
|
|
58
63
|
Pattern rules are in `.claude/rules/`:
|
|
59
|
-
- `core/` - Allowed patterns, forbidden patterns, complexity scoring
|
|
64
|
+
- `core/` - Allowed patterns, forbidden patterns, complexity scoring, project ledger
|
|
60
65
|
- `patterns/` - Templates and patterns for plans, discovery, contracts
|
|
61
66
|
- `languages/` - Language-specific patterns (TypeScript, Python)
|
|
62
67
|
- `tools/` - Tool-specific patterns (Jest, Pytest, auth)
|