Skip to content

Commit 5148e2a

Browse files
clark-mackeyclark-mackey
committed
feat: implement Stories 8.6-8.11 agent-first features
All 6 stories implemented via rule + template changes only: - 8.6: Session Handoff Protocol (SESSION END section) - 8.7: Self-Assessed Token Counting (TOKEN SELF-ASSESSMENT section) - 8.8: Entry Verbosity Control (compact/standard formats) - 8.9: Cross-File Navigation Hints (CROSS-REFERENCES section) - 8.10: Stale Context Detection (staleness check in SESSION START) - 8.11: Archival Summary Index (summary lines in archive links) Zero new dependencies. 4 rule files + 2 templates updated. Files: product/ai-rules/*/log-file-maintenance.md, product/starter-packs/*/log-file-maintenance.md, product/templates/DEVLOG_template.md, product/templates/CHANGELOG_template.md, logs/CHANGELOG.md
1 parent 6811361 commit 5148e2a

File tree

7 files changed

+376
-24
lines changed

7 files changed

+376
-24
lines changed

‎logs/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2121

2222
### Added
2323

24+
- Implement Stories 8.6-8.11: Session Handoff, Token Self-Assessment, Entry Verbosity, Cross-References, Stale Context Detection, Archival Summaries. All 4 rule files + 2 templates updated. Files: `product/ai-rules/augment/log-file-maintenance.md`, `product/ai-rules/claude-code/log-file-maintenance.md`, `product/starter-packs/augment/.augment/rules/log-file-maintenance.md`, `product/starter-packs/claude-code/.claude/rules/log-file-maintenance.md`, `product/templates/DEVLOG_template.md`, `product/templates/CHANGELOG_template.md`. Commit: `d2611b7`
2425
- Stories 8.6-8.11: Agent-first gap analysis - 6 new stories for Epic 8: Session Handoff Protocol, Self-Assessed Token Counting, Entry Verbosity Control, Cross-File Navigation Hints, Stale Context Detection, Archival Summary Index. All implementable via rule/template changes only - zero new dependencies. Files: `project/specs/prd.md`. Commit: `4c97104`
2526
- Epic 8: AI Context Optimization (NEW) - Replaced old Epic 8 with 5 mission-aligned stories: Smart Context Summarization (<500 tokens), Token Budget Dashboard, AI-Optimized Document Templates, Intelligent Archival Triggers, Context Relevance Scoring. All features directly help AI agents not get lost and not waste tokens. Files: `project/specs/prd.md`. Commit: `b9a9a38`
2627
- Project navigation guide for autonomous agents - Created `project/README.md` explaining directory structure, source of truth hierarchy, and what files to reference. Files: `project/README.md`. Commit: `9ebb777`

‎product/ai-rules/augment/log-file-maintenance.md‎

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,90 @@ This rule is ALWAYS active. Violations require immediate self-correction.
7878
## 🔄 SESSION START
7979

8080
**At start of EVERY session:**
81-
1. Read `logs/DEVLOG.md` → "Current Context" section
82-
2. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
81+
1. Read `logs/DEVLOG.md` → "Last Session" section (if exists) for handoff context
82+
2. Read `logs/DEVLOG.md` → "Current Context" section
83+
3. **Staleness check:** If `Last Updated` date is >7 days old, update Current Context BEFORE other work
84+
- Tell user: "Current Context is X days old. Updating before proceeding."
85+
- Update: version, phase, objectives, recent changes
86+
- Set new `Last Updated` date
87+
4. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
88+
89+
---
90+
91+
## 🔚 SESSION END
92+
93+
**Before ending a session, write a handoff note:**
94+
95+
1. Update `logs/DEVLOG.md` → "Last Session" section (overwrite previous)
96+
2. Format (3 bullets max, <150 tokens):
97+
```
98+
## Last Session
99+
- **Done:** [What was completed this session]
100+
- **In Progress:** [What's partially done, current state]
101+
- **Next:** [What the next session should start with]
102+
- **Branch:** `branch-name` | **Last Commit:** `hash`
103+
```
104+
3. Stage and commit with other changes (or amend last commit)
105+
106+
---
107+
108+
## 📊 TOKEN SELF-ASSESSMENT
109+
110+
**Heuristic:** ~4 characters = 1 token. Use this to self-regulate without running scripts.
111+
112+
**Quick reference:**
113+
- 1 line (~80 chars) ≈ 20 tokens
114+
- 1 paragraph (~320 chars) ≈ 80 tokens
115+
- 1 CHANGELOG entry ≈ 60-80 tokens
116+
- 1 DEVLOG compact entry ≈ 50-80 tokens
117+
- 1 DEVLOG standard entry ≈ 150-250 tokens
118+
119+
**Budgets:**
120+
- CHANGELOG: <10,000 tokens
121+
- DEVLOG: <15,000 tokens
122+
- Combined: <25,000 tokens
123+
124+
**Before writing:** Estimate entry size. If file is near budget, archive oldest entries first.
125+
126+
---
127+
128+
## ✏️ ENTRY VERBOSITY
129+
130+
**Two DEVLOG entry formats:**
131+
132+
**Compact format** (default for routine work, ~50-80 tokens):
133+
```
134+
### YYYY-MM-DD: Title
135+
Why/what in 1-2 sentences. Context or rationale.
136+
Files: `file1.py`, `file2.py`
137+
```
138+
139+
**Standard format** (for major decisions, incidents, milestones, ~150-250 tokens):
140+
```
141+
### YYYY-MM-DD: Title
142+
**The Situation:** ...
143+
**The Decision:** ...
144+
**Why This Matters:** ...
145+
**Files Changed:** ...
146+
```
147+
148+
**Decision guide:** If it needs an ADR → use standard. Otherwise → compact.
149+
150+
---
151+
152+
## 🔗 CROSS-REFERENCES
153+
154+
**When writing entries that relate across files, add navigation hints:**
155+
156+
- CHANGELOG entry with a DEVLOG decision: append `→ DEVLOG YYYY-MM-DD`
157+
- DEVLOG entry referencing a specific version: append `→ CHANGELOG vX.Y.Z`
158+
159+
**Example:**
160+
```
161+
- Fixed token refresh bug. Files: `src/auth.js`. Commit: `abc123` → DEVLOG 2026-02-06
162+
```
163+
164+
Hints are optional - only add when a cross-reference exists.
83165

84166
---
85167

@@ -89,7 +171,9 @@ This rule is ALWAYS active. Violations require immediate self-correction.
89171

90172
**Action:** Archive OLDEST entries first until under budget
91173
1. Move oldest entries to `logs/archive/[FILENAME]-YYYY-MM.md`
92-
2. Re-run validation to confirm
174+
2. Add summary line to the Archive section of the source file:
175+
`- [FILENAME-YYYY-MM.md](archive/FILENAME-YYYY-MM.md) - Brief description of contents`
176+
3. Re-run validation to confirm
93177

94178
**Key:** Archive by TOKEN COUNT, not date. Recent entries may need archiving if over budget.
95179

‎product/ai-rules/claude-code/log-file-maintenance.md‎

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,8 +78,90 @@ This rule is ALWAYS active. Violations require immediate self-correction.
7878
## 🔄 SESSION START
7979

8080
**At start of EVERY session:**
81-
1. Read `logs/DEVLOG.md` → "Current Context" section
82-
2. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
81+
1. Read `logs/DEVLOG.md` → "Last Session" section (if exists) for handoff context
82+
2. Read `logs/DEVLOG.md` → "Current Context" section
83+
3. **Staleness check:** If `Last Updated` date is >7 days old, update Current Context BEFORE other work
84+
- Tell user: "Current Context is X days old. Updating before proceeding."
85+
- Update: version, phase, objectives, recent changes
86+
- Set new `Last Updated` date
87+
4. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
88+
89+
---
90+
91+
## 🔚 SESSION END
92+
93+
**Before ending a session, write a handoff note:**
94+
95+
1. Update `logs/DEVLOG.md` → "Last Session" section (overwrite previous)
96+
2. Format (3 bullets max, <150 tokens):
97+
```
98+
## Last Session
99+
- **Done:** [What was completed this session]
100+
- **In Progress:** [What's partially done, current state]
101+
- **Next:** [What the next session should start with]
102+
- **Branch:** `branch-name` | **Last Commit:** `hash`
103+
```
104+
3. Stage and commit with other changes (or amend last commit)
105+
106+
---
107+
108+
## 📊 TOKEN SELF-ASSESSMENT
109+
110+
**Heuristic:** ~4 characters = 1 token. Use this to self-regulate without running scripts.
111+
112+
**Quick reference:**
113+
- 1 line (~80 chars) ≈ 20 tokens
114+
- 1 paragraph (~320 chars) ≈ 80 tokens
115+
- 1 CHANGELOG entry ≈ 60-80 tokens
116+
- 1 DEVLOG compact entry ≈ 50-80 tokens
117+
- 1 DEVLOG standard entry ≈ 150-250 tokens
118+
119+
**Budgets:**
120+
- CHANGELOG: <10,000 tokens
121+
- DEVLOG: <15,000 tokens
122+
- Combined: <25,000 tokens
123+
124+
**Before writing:** Estimate entry size. If file is near budget, archive oldest entries first.
125+
126+
---
127+
128+
## ✏️ ENTRY VERBOSITY
129+
130+
**Two DEVLOG entry formats:**
131+
132+
**Compact format** (default for routine work, ~50-80 tokens):
133+
```
134+
### YYYY-MM-DD: Title
135+
Why/what in 1-2 sentences. Context or rationale.
136+
Files: `file1.py`, `file2.py`
137+
```
138+
139+
**Standard format** (for major decisions, incidents, milestones, ~150-250 tokens):
140+
```
141+
### YYYY-MM-DD: Title
142+
**The Situation:** ...
143+
**The Decision:** ...
144+
**Why This Matters:** ...
145+
**Files Changed:** ...
146+
```
147+
148+
**Decision guide:** If it needs an ADR → use standard. Otherwise → compact.
149+
150+
---
151+
152+
## 🔗 CROSS-REFERENCES
153+
154+
**When writing entries that relate across files, add navigation hints:**
155+
156+
- CHANGELOG entry with a DEVLOG decision: append `→ DEVLOG YYYY-MM-DD`
157+
- DEVLOG entry referencing a specific version: append `→ CHANGELOG vX.Y.Z`
158+
159+
**Example:**
160+
```
161+
- Fixed token refresh bug. Files: `src/auth.js`. Commit: `abc123` → DEVLOG 2026-02-06
162+
```
163+
164+
Hints are optional - only add when a cross-reference exists.
83165

84166
---
85167

@@ -89,7 +171,9 @@ This rule is ALWAYS active. Violations require immediate self-correction.
89171

90172
**Action:** Archive OLDEST entries first until under budget
91173
1. Move oldest entries to `logs/archive/[FILENAME]-YYYY-MM.md`
92-
2. Re-run validation to confirm
174+
2. Add summary line to the Archive section of the source file:
175+
`- [FILENAME-YYYY-MM.md](archive/FILENAME-YYYY-MM.md) - Brief description of contents`
176+
3. Re-run validation to confirm
93177

94178
**Key:** Archive by TOKEN COUNT, not date. Recent entries may need archiving if over budget.
95179

‎product/starter-packs/augment/.augment/rules/log-file-maintenance.md‎

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,8 +81,90 @@ This rule is ALWAYS active. Violations require immediate self-correction.
8181

8282
**At start of EVERY session:**
8383
1. Read `.logfile-config.yml` → `paths.devlog` to find DEVLOG
84-
2. Read DEVLOG → "Current Context" section
85-
3. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
84+
2. Read DEVLOG → "Last Session" section (if exists) for handoff context
85+
3. Read DEVLOG → "Current Context" section
86+
4. **Staleness check:** If `Last Updated` date is >7 days old, update Current Context BEFORE other work
87+
- Tell user: "Current Context is X days old. Updating before proceeding."
88+
- Update: version, phase, objectives, recent changes
89+
- Set new `Last Updated` date
90+
5. Acknowledge: "Context read. Version [x], Phase [y], Objectives: [z]"
91+
92+
---
93+
94+
## 🔚 SESSION END
95+
96+
**Before ending a session, write a handoff note:**
97+
98+
1. Update DEVLOG → "Last Session" section (overwrite previous)
99+
2. Format (3 bullets max, <150 tokens):
100+
```
101+
## Last Session
102+
- **Done:** [What was completed this session]
103+
- **In Progress:** [What's partially done, current state]
104+
- **Next:** [What the next session should start with]
105+
- **Branch:** `branch-name` | **Last Commit:** `hash`
106+
```
107+
3. Stage and commit with other changes (or amend last commit)
108+
109+
---
110+
111+
## 📊 TOKEN SELF-ASSESSMENT
112+
113+
**Heuristic:** ~4 characters = 1 token. Use this to self-regulate without running scripts.
114+
115+
**Quick reference:**
116+
- 1 line (~80 chars) ≈ 20 tokens
117+
- 1 paragraph (~320 chars) ≈ 80 tokens
118+
- 1 CHANGELOG entry ≈ 60-80 tokens
119+
- 1 DEVLOG compact entry ≈ 50-80 tokens
120+
- 1 DEVLOG standard entry ≈ 150-250 tokens
121+
122+
**Budgets:**
123+
- CHANGELOG: <10,000 tokens
124+
- DEVLOG: <15,000 tokens
125+
- Combined: <25,000 tokens
126+
127+
**Before writing:** Estimate entry size. If file is near budget, archive oldest entries first.
128+
129+
---
130+
131+
## ✏️ ENTRY VERBOSITY
132+
133+
**Two DEVLOG entry formats:**
134+
135+
**Compact format** (default for routine work, ~50-80 tokens):
136+
```
137+
### YYYY-MM-DD: Title
138+
Why/what in 1-2 sentences. Context or rationale.
139+
Files: `file1.py`, `file2.py`
140+
```
141+
142+
**Standard format** (for major decisions, incidents, milestones, ~150-250 tokens):
143+
```
144+
### YYYY-MM-DD: Title
145+
**The Situation:** ...
146+
**The Decision:** ...
147+
**Why This Matters:** ...
148+
**Files Changed:** ...
149+
```
150+
151+
**Decision guide:** If it needs an ADR → use standard. Otherwise → compact.
152+
153+
---
154+
155+
## 🔗 CROSS-REFERENCES
156+
157+
**When writing entries that relate across files, add navigation hints:**
158+
159+
- CHANGELOG entry with a DEVLOG decision: append `→ DEVLOG YYYY-MM-DD`
160+
- DEVLOG entry referencing a specific version: append `→ CHANGELOG vX.Y.Z`
161+
162+
**Example:**
163+
```
164+
- Fixed token refresh bug. Files: `src/auth.js`. Commit: `abc123` → DEVLOG 2026-02-06
165+
```
166+
167+
Hints are optional - only add when a cross-reference exists.
86168

87169
---
88170

@@ -92,7 +174,9 @@ This rule is ALWAYS active. Violations require immediate self-correction.
92174

93175
**Action:** Archive OLDEST entries first until under budget
94176
1. Move oldest entries to archive folder (see `.logfile-config.yml`)
95-
2. Re-run validation to confirm
177+
2. Add summary line to the Archive section of the source file:
178+
`- [FILENAME-YYYY-MM.md](archive/FILENAME-YYYY-MM.md) - Brief description of contents`
179+
3. Re-run validation to confirm
96180

97181
**Key:** Archive by TOKEN COUNT, not date. Recent entries may need archiving if over budget.
98182

0 commit comments

Comments
 (0)