@mmnto/cli 0.1.0 → 0.2.0
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/LICENSE +21 -0
- package/dist/commands/briefing.js +30 -30
- package/dist/commands/handoff.js +33 -33
- package/dist/commands/init.js +38 -38
- package/dist/commands/install-hooks.js +9 -9
- package/dist/commands/learn.js +26 -26
- package/dist/commands/shield.js +33 -33
- package/dist/commands/spec.js +38 -38
- package/dist/commands/triage.js +30 -30
- package/dist/index.js +0 -0
- package/package.json +51 -51
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Matt Sutton
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -9,36 +9,36 @@ const TAG = 'Briefing';
|
|
|
9
9
|
const MAX_SPEC_RESULTS = 5;
|
|
10
10
|
const MAX_SESSION_RESULTS = 5;
|
|
11
11
|
// ─── System prompt ──────────────────────────────────────
|
|
12
|
-
const SYSTEM_PROMPT = `# Briefing System Prompt — Session Startup Briefing
|
|
13
|
-
|
|
14
|
-
## Purpose
|
|
15
|
-
Produce a session startup briefing that orients the developer at the start of an AI-assisted work session.
|
|
16
|
-
|
|
17
|
-
## Role
|
|
18
|
-
You are a technical project assistant producing a quick-start briefing. You have access to the current git state, open pull requests, and project knowledge from Totem. Your job is to synthesize this into an actionable summary so the developer knows exactly where they left off and what to do next.
|
|
19
|
-
|
|
20
|
-
## Rules
|
|
21
|
-
- Reference PRs by number (#NNN) and branch name
|
|
22
|
-
- Reference issues by number (#NNN) when they appear in Totem knowledge
|
|
23
|
-
- Be opinionated about what the recommended first action should be
|
|
24
|
-
- Be concise — this is a startup briefing, not a project plan
|
|
25
|
-
- If there are uncommitted changes, flag them prominently
|
|
26
|
-
- If there are no open PRs, say so
|
|
27
|
-
|
|
28
|
-
## Output Format
|
|
29
|
-
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
30
|
-
|
|
31
|
-
### Session Context
|
|
32
|
-
[Current branch, uncommitted changes summary. If working tree is clean, say so. If on a feature branch, note what it likely relates to.]
|
|
33
|
-
|
|
34
|
-
### Open PRs
|
|
35
|
-
[List of open PRs with number, title, and branch. If none, say "No open PRs." Highlight any that are the developer's current branch.]
|
|
36
|
-
|
|
37
|
-
### Active Priorities
|
|
38
|
-
[Key priorities and recent work context from Totem knowledge — what was recently worked on, what specs are active, what sessions covered. If no relevant knowledge, say "No recent context found in Totem index."]
|
|
39
|
-
|
|
40
|
-
### Recommended First Action
|
|
41
|
-
[Single clear recommendation for what the developer should do first in this session. Consider: uncommitted work to commit/continue, PRs to review/merge, next issue to pick up.]
|
|
12
|
+
const SYSTEM_PROMPT = `# Briefing System Prompt — Session Startup Briefing
|
|
13
|
+
|
|
14
|
+
## Purpose
|
|
15
|
+
Produce a session startup briefing that orients the developer at the start of an AI-assisted work session.
|
|
16
|
+
|
|
17
|
+
## Role
|
|
18
|
+
You are a technical project assistant producing a quick-start briefing. You have access to the current git state, open pull requests, and project knowledge from Totem. Your job is to synthesize this into an actionable summary so the developer knows exactly where they left off and what to do next.
|
|
19
|
+
|
|
20
|
+
## Rules
|
|
21
|
+
- Reference PRs by number (#NNN) and branch name
|
|
22
|
+
- Reference issues by number (#NNN) when they appear in Totem knowledge
|
|
23
|
+
- Be opinionated about what the recommended first action should be
|
|
24
|
+
- Be concise — this is a startup briefing, not a project plan
|
|
25
|
+
- If there are uncommitted changes, flag them prominently
|
|
26
|
+
- If there are no open PRs, say so
|
|
27
|
+
|
|
28
|
+
## Output Format
|
|
29
|
+
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
30
|
+
|
|
31
|
+
### Session Context
|
|
32
|
+
[Current branch, uncommitted changes summary. If working tree is clean, say so. If on a feature branch, note what it likely relates to.]
|
|
33
|
+
|
|
34
|
+
### Open PRs
|
|
35
|
+
[List of open PRs with number, title, and branch. If none, say "No open PRs." Highlight any that are the developer's current branch.]
|
|
36
|
+
|
|
37
|
+
### Active Priorities
|
|
38
|
+
[Key priorities and recent work context from Totem knowledge — what was recently worked on, what specs are active, what sessions covered. If no relevant knowledge, say "No recent context found in Totem index."]
|
|
39
|
+
|
|
40
|
+
### Recommended First Action
|
|
41
|
+
[Single clear recommendation for what the developer should do first in this session. Consider: uncommitted work to commit/continue, PRs to review/merge, next issue to pick up.]
|
|
42
42
|
`;
|
|
43
43
|
// ─── GitHub helpers ─────────────────────────────────────
|
|
44
44
|
const GhPrListItemSchema = z.object({
|
package/dist/commands/handoff.js
CHANGED
|
@@ -7,39 +7,39 @@ const TAG = 'Handoff';
|
|
|
7
7
|
const MAX_DIFF_CHARS = 50_000;
|
|
8
8
|
const LESSONS_TAIL_LINES = 100;
|
|
9
9
|
// ─── System prompt ──────────────────────────────────────
|
|
10
|
-
const SYSTEM_PROMPT = `# Handoff System Prompt — End-of-Session State Transfer
|
|
11
|
-
|
|
12
|
-
## Purpose
|
|
13
|
-
Produce an end-of-session handoff snapshot that captures everything the next session (or the next developer) needs to resume work immediately.
|
|
14
|
-
|
|
15
|
-
## Role
|
|
16
|
-
You are writing a concise, tactical "End of Shift" handoff. You have access to the current git state, uncommitted changes, and lessons learned during this session. Your job is to synthesize this into a snapshot that lets the next session bootstrap instantly — no detective work required.
|
|
17
|
-
|
|
18
|
-
## Rules
|
|
19
|
-
- Be concrete and specific — file paths, branch names, issue numbers
|
|
20
|
-
- Distinguish between what IS done vs what NEEDS to be done next
|
|
21
|
-
- If there are uncommitted changes, describe what they represent and whether they look ready to commit
|
|
22
|
-
- If the working tree is clean, say so and focus on what was accomplished and what's next
|
|
23
|
-
- Capture any lessons or traps discovered during this session
|
|
24
|
-
- Be concise — this is a tactical handoff, not a retrospective
|
|
25
|
-
|
|
26
|
-
## Output Format
|
|
27
|
-
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
28
|
-
|
|
29
|
-
### Branch & State
|
|
30
|
-
[Current branch, clean/dirty status, what the branch represents]
|
|
31
|
-
|
|
32
|
-
### What Was Done
|
|
33
|
-
[Summary of work completed this session based on the diff and git state. If no changes, say "No uncommitted changes — session may have been exploratory or changes were already committed."]
|
|
34
|
-
|
|
35
|
-
### Uncommitted Changes
|
|
36
|
-
[Description of what the uncommitted changes contain and their state (staged vs unstaged). If clean, say "Working tree is clean."]
|
|
37
|
-
|
|
38
|
-
### Lessons & Traps
|
|
39
|
-
[Lessons learned during this session from the memory file. If none, say "No new lessons recorded this session."]
|
|
40
|
-
|
|
41
|
-
### Next Steps
|
|
42
|
-
[Clear, ordered list of what the next session should do first. Be specific — not "continue working" but "finish implementing X in file Y, then run tests."]
|
|
10
|
+
const SYSTEM_PROMPT = `# Handoff System Prompt — End-of-Session State Transfer
|
|
11
|
+
|
|
12
|
+
## Purpose
|
|
13
|
+
Produce an end-of-session handoff snapshot that captures everything the next session (or the next developer) needs to resume work immediately.
|
|
14
|
+
|
|
15
|
+
## Role
|
|
16
|
+
You are writing a concise, tactical "End of Shift" handoff. You have access to the current git state, uncommitted changes, and lessons learned during this session. Your job is to synthesize this into a snapshot that lets the next session bootstrap instantly — no detective work required.
|
|
17
|
+
|
|
18
|
+
## Rules
|
|
19
|
+
- Be concrete and specific — file paths, branch names, issue numbers
|
|
20
|
+
- Distinguish between what IS done vs what NEEDS to be done next
|
|
21
|
+
- If there are uncommitted changes, describe what they represent and whether they look ready to commit
|
|
22
|
+
- If the working tree is clean, say so and focus on what was accomplished and what's next
|
|
23
|
+
- Capture any lessons or traps discovered during this session
|
|
24
|
+
- Be concise — this is a tactical handoff, not a retrospective
|
|
25
|
+
|
|
26
|
+
## Output Format
|
|
27
|
+
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
28
|
+
|
|
29
|
+
### Branch & State
|
|
30
|
+
[Current branch, clean/dirty status, what the branch represents]
|
|
31
|
+
|
|
32
|
+
### What Was Done
|
|
33
|
+
[Summary of work completed this session based on the diff and git state. If no changes, say "No uncommitted changes — session may have been exploratory or changes were already committed."]
|
|
34
|
+
|
|
35
|
+
### Uncommitted Changes
|
|
36
|
+
[Description of what the uncommitted changes contain and their state (staged vs unstaged). If clean, say "Working tree is clean."]
|
|
37
|
+
|
|
38
|
+
### Lessons & Traps
|
|
39
|
+
[Lessons learned during this session from the memory file. If none, say "No new lessons recorded this session."]
|
|
40
|
+
|
|
41
|
+
### Next Steps
|
|
42
|
+
[Clear, ordered list of what the next session should do first. Be specific — not "continue working" but "finish implementing X in file Y, then run tests."]
|
|
43
43
|
`;
|
|
44
44
|
// ─── Lessons file reader ────────────────────────────────
|
|
45
45
|
function readRecentLessons(cwd, totemDir) {
|
package/dist/commands/init.js
CHANGED
|
@@ -3,27 +3,27 @@ import * as path from 'node:path';
|
|
|
3
3
|
import { stdin as input, stdout as output } from 'node:process';
|
|
4
4
|
import * as readline from 'node:readline/promises';
|
|
5
5
|
import { installPostMergeHook } from './install-hooks.js';
|
|
6
|
-
const AI_PROMPT_BLOCK = `
|
|
7
|
-
|
|
8
|
-
## Totem AI Integration (Auto-Generated)
|
|
9
|
-
You have access to the Totem MCP for long-term project memory. You MUST operate with the following reflexes:
|
|
10
|
-
|
|
11
|
-
### Memory Reflexes
|
|
12
|
-
1. **Pull Before Planning:** Before writing specs, architecture, or fixing complex bugs, use \`search_knowledge\` to retrieve domain constraints and past traps.
|
|
13
|
-
2. **Proactive Anchoring (The 3 Triggers):** You must autonomously call \`add_lesson\` when any of the following occur — do NOT wait for the user to ask:
|
|
14
|
-
- **The Trap Trigger:** If you spend >2 turns fixing a bug caused by a framework quirk, unexpected API response, or edge case. (Anchor the symptom + fix).
|
|
15
|
-
- **The Pivot Trigger:** If the user introduces a new architectural pattern or deprecates an old one. (Anchor the rule).
|
|
16
|
-
- **The Handoff Trigger:** At the end of a session or when wrapping up a complex feature, extract the non-obvious lessons learned and anchor them.
|
|
17
|
-
3. **Tool Preference (MCP over CLI):** Always prioritize using dedicated MCP tools (e.g., GitHub, Supabase, Vercel) over executing generic shell commands (like \`gh issue view\` or \`curl\`). MCP tools provide structured, un-truncated data optimized for your context window. Only fall back to bash execution if an MCP tool is unavailable or fails.
|
|
18
|
-
|
|
19
|
-
Lessons are automatically re-indexed in the background after each \`add_lesson\` call — no manual sync needed.
|
|
20
|
-
|
|
21
|
-
### Workflow Orchestrator Rituals
|
|
22
|
-
Totem provides CLI commands that map to your development lifecycle. Use them at these moments:
|
|
23
|
-
1. **Start of Session:** Run \`totem briefing\` to get oriented with current branch state, open PRs, and recent context. Run \`totem triage\` if you need to pick a new task.
|
|
24
|
-
2. **Before Implementation:** Run \`totem spec <issue-url-or-topic>\` to generate an architectural plan and review related context before writing code.
|
|
25
|
-
3. **Before PR/Push:** Run \`totem shield\` to analyze uncommitted changes against project knowledge — catches architectural drift and pattern violations.
|
|
26
|
-
4. **End of Session:** Run \`totem handoff\` to generate a snapshot for the next agent session with current progress and open threads.
|
|
6
|
+
const AI_PROMPT_BLOCK = `
|
|
7
|
+
|
|
8
|
+
## Totem AI Integration (Auto-Generated)
|
|
9
|
+
You have access to the Totem MCP for long-term project memory. You MUST operate with the following reflexes:
|
|
10
|
+
|
|
11
|
+
### Memory Reflexes
|
|
12
|
+
1. **Pull Before Planning:** Before writing specs, architecture, or fixing complex bugs, use \`search_knowledge\` to retrieve domain constraints and past traps.
|
|
13
|
+
2. **Proactive Anchoring (The 3 Triggers):** You must autonomously call \`add_lesson\` when any of the following occur — do NOT wait for the user to ask:
|
|
14
|
+
- **The Trap Trigger:** If you spend >2 turns fixing a bug caused by a framework quirk, unexpected API response, or edge case. (Anchor the symptom + fix).
|
|
15
|
+
- **The Pivot Trigger:** If the user introduces a new architectural pattern or deprecates an old one. (Anchor the rule).
|
|
16
|
+
- **The Handoff Trigger:** At the end of a session or when wrapping up a complex feature, extract the non-obvious lessons learned and anchor them.
|
|
17
|
+
3. **Tool Preference (MCP over CLI):** Always prioritize using dedicated MCP tools (e.g., GitHub, Supabase, Vercel) over executing generic shell commands (like \`gh issue view\` or \`curl\`). MCP tools provide structured, un-truncated data optimized for your context window. Only fall back to bash execution if an MCP tool is unavailable or fails.
|
|
18
|
+
|
|
19
|
+
Lessons are automatically re-indexed in the background after each \`add_lesson\` call — no manual sync needed.
|
|
20
|
+
|
|
21
|
+
### Workflow Orchestrator Rituals
|
|
22
|
+
Totem provides CLI commands that map to your development lifecycle. Use them at these moments:
|
|
23
|
+
1. **Start of Session:** Run \`totem briefing\` to get oriented with current branch state, open PRs, and recent context. Run \`totem triage\` if you need to pick a new task.
|
|
24
|
+
2. **Before Implementation:** Run \`totem spec <issue-url-or-topic>\` to generate an architectural plan and review related context before writing code.
|
|
25
|
+
3. **Before PR/Push:** Run \`totem shield\` to analyze uncommitted changes against project knowledge — catches architectural drift and pattern violations.
|
|
26
|
+
4. **End of Session:** Run \`totem handoff\` to generate a snapshot for the next agent session with current progress and open threads.
|
|
27
27
|
`;
|
|
28
28
|
function detectProject(cwd) {
|
|
29
29
|
const exists = (p) => fs.existsSync(path.join(cwd, p));
|
|
@@ -93,23 +93,23 @@ function generateConfig(targets, provider) {
|
|
|
93
93
|
const embeddingBlock = provider === 'openai'
|
|
94
94
|
? ` embedding: { provider: 'openai', model: 'text-embedding-3-small' },`
|
|
95
95
|
: ` embedding: { provider: 'ollama', model: 'nomic-embed-text', baseUrl: 'http://localhost:11434' },`;
|
|
96
|
-
return `import type { TotemConfig } from '@mmnto/totem';
|
|
97
|
-
|
|
98
|
-
const config: TotemConfig = {
|
|
99
|
-
targets: [
|
|
100
|
-
${formatTargets(targets)}
|
|
101
|
-
],
|
|
102
|
-
|
|
103
|
-
${embeddingBlock}
|
|
104
|
-
|
|
105
|
-
orchestrator: {
|
|
106
|
-
provider: 'shell',
|
|
107
|
-
command: 'gemini --model {model} -o json -e none < {file}',
|
|
108
|
-
defaultModel: 'gemini-3-flash-preview',
|
|
109
|
-
},
|
|
110
|
-
};
|
|
111
|
-
|
|
112
|
-
export default config;
|
|
96
|
+
return `import type { TotemConfig } from '@mmnto/totem';
|
|
97
|
+
|
|
98
|
+
const config: TotemConfig = {
|
|
99
|
+
targets: [
|
|
100
|
+
${formatTargets(targets)}
|
|
101
|
+
],
|
|
102
|
+
|
|
103
|
+
${embeddingBlock}
|
|
104
|
+
|
|
105
|
+
orchestrator: {
|
|
106
|
+
provider: 'shell',
|
|
107
|
+
command: 'gemini --model {model} -o json -e none < {file}',
|
|
108
|
+
defaultModel: 'gemini-3-flash-preview',
|
|
109
|
+
},
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
export default config;
|
|
113
113
|
`;
|
|
114
114
|
}
|
|
115
115
|
export async function initCommand() {
|
|
@@ -13,11 +13,11 @@ function detectSyncCommand(cwd) {
|
|
|
13
13
|
return 'npx totem sync --incremental';
|
|
14
14
|
}
|
|
15
15
|
function buildHookContent(syncCmd) {
|
|
16
|
-
return `#!/bin/sh
|
|
17
|
-
# ${TOTEM_HOOK_MARKER} — background re-index after pull/merge.
|
|
18
|
-
|
|
19
|
-
echo "[totem] Triggering background re-index..."
|
|
20
|
-
(${syncCmd} > .git/totem-sync.log 2>&1) &
|
|
16
|
+
return `#!/bin/sh
|
|
17
|
+
# ${TOTEM_HOOK_MARKER} — background re-index after pull/merge.
|
|
18
|
+
|
|
19
|
+
echo "[totem] Triggering background re-index..."
|
|
20
|
+
(${syncCmd} > .git/totem-sync.log 2>&1) &
|
|
21
21
|
`;
|
|
22
22
|
}
|
|
23
23
|
function detectHookManager(cwd) {
|
|
@@ -91,10 +91,10 @@ export async function installPostMergeHook(cwd, rl) {
|
|
|
91
91
|
}
|
|
92
92
|
// Append to existing hook
|
|
93
93
|
const separator = existing.endsWith('\n') ? '' : '\n';
|
|
94
|
-
const appendBlock = `${separator}
|
|
95
|
-
# ${TOTEM_HOOK_MARKER} — background re-index after pull/merge.
|
|
96
|
-
echo "[totem] Triggering background re-index..."
|
|
97
|
-
(${syncCmd} > .git/totem-sync.log 2>&1) &
|
|
94
|
+
const appendBlock = `${separator}
|
|
95
|
+
# ${TOTEM_HOOK_MARKER} — background re-index after pull/merge.
|
|
96
|
+
echo "[totem] Triggering background re-index..."
|
|
97
|
+
(${syncCmd} > .git/totem-sync.log 2>&1) &
|
|
98
98
|
`;
|
|
99
99
|
fs.appendFileSync(hookPath, appendBlock);
|
|
100
100
|
console.log('[Totem] Appended post-merge hook to existing hook file.');
|
package/dist/commands/learn.js
CHANGED
|
@@ -9,32 +9,32 @@ const TAG = 'Learn';
|
|
|
9
9
|
const MAX_EXISTING_LESSONS = 10;
|
|
10
10
|
const MAX_REVIEW_BODY_CHARS = 50_000;
|
|
11
11
|
// ─── System prompt ──────────────────────────────────────
|
|
12
|
-
const SYSTEM_PROMPT = `# Learn System Prompt — PR Lesson Extraction
|
|
13
|
-
|
|
14
|
-
## Purpose
|
|
15
|
-
Extract tactical lessons from a pull request's review comments and discussion.
|
|
16
|
-
|
|
17
|
-
## Role
|
|
18
|
-
You are a knowledge curator analyzing a PR's review threads. Your job is to distill non-obvious lessons — traps, patterns, decisions with rationale — that will prevent future mistakes.
|
|
19
|
-
|
|
20
|
-
## Rules
|
|
21
|
-
- Extract ONLY non-obvious lessons (traps, surprising behaviors, pattern decisions with rationale)
|
|
22
|
-
- Ignore GCA boilerplate, simple acknowledgments, nits, and formatting suggestions
|
|
23
|
-
- When a suggestion was DECLINED, the author's rationale is often the most valuable lesson
|
|
24
|
-
- Each lesson should be 1-2 sentences capturing WHAT happened and WHY it matters
|
|
25
|
-
- Tags should be lowercase, comma-separated, reflecting the technical domain
|
|
26
|
-
- If existing lessons are provided, do NOT extract duplicates or near-duplicates
|
|
27
|
-
- If no lessons are worth extracting, output exactly: NONE
|
|
28
|
-
|
|
29
|
-
## Output Format
|
|
30
|
-
For each lesson, use this exact delimiter format:
|
|
31
|
-
|
|
32
|
-
---LESSON---
|
|
33
|
-
Tags: tag1, tag2, tag3
|
|
34
|
-
The lesson text. One or two sentences capturing the trap/pattern and WHY it matters.
|
|
35
|
-
---END---
|
|
36
|
-
|
|
37
|
-
If no lessons found, output exactly: NONE
|
|
12
|
+
const SYSTEM_PROMPT = `# Learn System Prompt — PR Lesson Extraction
|
|
13
|
+
|
|
14
|
+
## Purpose
|
|
15
|
+
Extract tactical lessons from a pull request's review comments and discussion.
|
|
16
|
+
|
|
17
|
+
## Role
|
|
18
|
+
You are a knowledge curator analyzing a PR's review threads. Your job is to distill non-obvious lessons — traps, patterns, decisions with rationale — that will prevent future mistakes.
|
|
19
|
+
|
|
20
|
+
## Rules
|
|
21
|
+
- Extract ONLY non-obvious lessons (traps, surprising behaviors, pattern decisions with rationale)
|
|
22
|
+
- Ignore GCA boilerplate, simple acknowledgments, nits, and formatting suggestions
|
|
23
|
+
- When a suggestion was DECLINED, the author's rationale is often the most valuable lesson
|
|
24
|
+
- Each lesson should be 1-2 sentences capturing WHAT happened and WHY it matters
|
|
25
|
+
- Tags should be lowercase, comma-separated, reflecting the technical domain
|
|
26
|
+
- If existing lessons are provided, do NOT extract duplicates or near-duplicates
|
|
27
|
+
- If no lessons are worth extracting, output exactly: NONE
|
|
28
|
+
|
|
29
|
+
## Output Format
|
|
30
|
+
For each lesson, use this exact delimiter format:
|
|
31
|
+
|
|
32
|
+
---LESSON---
|
|
33
|
+
Tags: tag1, tag2, tag3
|
|
34
|
+
The lesson text. One or two sentences capturing the trap/pattern and WHY it matters.
|
|
35
|
+
---END---
|
|
36
|
+
|
|
37
|
+
If no lessons found, output exactly: NONE
|
|
38
38
|
`;
|
|
39
39
|
// ─── GitHub helpers ─────────────────────────────────────
|
|
40
40
|
const GhPrSchema = z.object({
|
package/dist/commands/shield.js
CHANGED
|
@@ -10,39 +10,39 @@ const MAX_SPEC_RESULTS = 3;
|
|
|
10
10
|
const MAX_SESSION_RESULTS = 5;
|
|
11
11
|
const MAX_CODE_RESULTS = 5;
|
|
12
12
|
// ─── System prompt ──────────────────────────────────────
|
|
13
|
-
const SYSTEM_PROMPT = `# Shield System Prompt — Pre-Flight Code Review
|
|
14
|
-
|
|
15
|
-
## Purpose
|
|
16
|
-
Perform a pre-flight code review on a git diff, using project-specific knowledge to catch traps and anti-patterns before a PR is opened.
|
|
17
|
-
|
|
18
|
-
## Role
|
|
19
|
-
You are a senior code reviewer analyzing a diff against the project's accumulated knowledge: past session lessons, architectural specs, and codebase conventions. Flag issues the developer might miss, especially ones that have caused problems before.
|
|
20
|
-
|
|
21
|
-
## Rules
|
|
22
|
-
- Focus on the DIFF — only comment on code that is actually changing
|
|
23
|
-
- Reference specific lines/hunks from the diff when flagging issues
|
|
24
|
-
- Cite Totem knowledge when it directly applies (e.g., "Session #142 found that...")
|
|
25
|
-
- Distinguish severity: CRITICAL (must fix), WARNING (should fix), INFO (consider)
|
|
26
|
-
- Be concise — this is a pre-flight check, not a full RFC
|
|
27
|
-
- If the diff looks clean and follows all known patterns, say so
|
|
28
|
-
|
|
29
|
-
## Output Format
|
|
30
|
-
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
31
|
-
|
|
32
|
-
### Summary
|
|
33
|
-
[1-2 sentences describing what this diff does at a high level]
|
|
34
|
-
|
|
35
|
-
### Critical Issues
|
|
36
|
-
[Issues that MUST be fixed before merging. If none, say "None found."]
|
|
37
|
-
|
|
38
|
-
### Warnings
|
|
39
|
-
[Issues that SHOULD be addressed. Include pattern violations, potential regressions, and lessons from past sessions. If none, say "None found."]
|
|
40
|
-
|
|
41
|
-
### Suggestions
|
|
42
|
-
[Optional improvements and style notes. If none, say "None."]
|
|
43
|
-
|
|
44
|
-
### Relevant History
|
|
45
|
-
[Specific past traps, lessons, or decisions from Totem knowledge that apply to this diff. If none, say "No relevant history found."]
|
|
13
|
+
const SYSTEM_PROMPT = `# Shield System Prompt — Pre-Flight Code Review
|
|
14
|
+
|
|
15
|
+
## Purpose
|
|
16
|
+
Perform a pre-flight code review on a git diff, using project-specific knowledge to catch traps and anti-patterns before a PR is opened.
|
|
17
|
+
|
|
18
|
+
## Role
|
|
19
|
+
You are a senior code reviewer analyzing a diff against the project's accumulated knowledge: past session lessons, architectural specs, and codebase conventions. Flag issues the developer might miss, especially ones that have caused problems before.
|
|
20
|
+
|
|
21
|
+
## Rules
|
|
22
|
+
- Focus on the DIFF — only comment on code that is actually changing
|
|
23
|
+
- Reference specific lines/hunks from the diff when flagging issues
|
|
24
|
+
- Cite Totem knowledge when it directly applies (e.g., "Session #142 found that...")
|
|
25
|
+
- Distinguish severity: CRITICAL (must fix), WARNING (should fix), INFO (consider)
|
|
26
|
+
- Be concise — this is a pre-flight check, not a full RFC
|
|
27
|
+
- If the diff looks clean and follows all known patterns, say so
|
|
28
|
+
|
|
29
|
+
## Output Format
|
|
30
|
+
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
31
|
+
|
|
32
|
+
### Summary
|
|
33
|
+
[1-2 sentences describing what this diff does at a high level]
|
|
34
|
+
|
|
35
|
+
### Critical Issues
|
|
36
|
+
[Issues that MUST be fixed before merging. If none, say "None found."]
|
|
37
|
+
|
|
38
|
+
### Warnings
|
|
39
|
+
[Issues that SHOULD be addressed. Include pattern violations, potential regressions, and lessons from past sessions. If none, say "None found."]
|
|
40
|
+
|
|
41
|
+
### Suggestions
|
|
42
|
+
[Optional improvements and style notes. If none, say "None."]
|
|
43
|
+
|
|
44
|
+
### Relevant History
|
|
45
|
+
[Specific past traps, lessons, or decisions from Totem knowledge that apply to this diff. If none, say "No relevant history found."]
|
|
46
46
|
`;
|
|
47
47
|
async function retrieveContext(query, store) {
|
|
48
48
|
const search = (typeFilter, maxResults) => store.search({ query, typeFilter, maxResults });
|
package/dist/commands/spec.js
CHANGED
|
@@ -7,44 +7,44 @@ import { formatResults, GH_TIMEOUT_MS, IS_WIN, loadConfig, loadEnv, resolveConfi
|
|
|
7
7
|
const TAG = 'Spec';
|
|
8
8
|
const QUERY_BODY_TRUNCATE = 500;
|
|
9
9
|
// ─── System prompt ──────────────────────────────────────
|
|
10
|
-
const SYSTEM_PROMPT = `# Spec System Prompt — Pre-Work Briefing
|
|
11
|
-
|
|
12
|
-
## Purpose
|
|
13
|
-
Produce a structured pre-work briefing for a GitHub issue before implementation begins.
|
|
14
|
-
|
|
15
|
-
## Role
|
|
16
|
-
You are a technical spec writer analyzing a GitHub issue and its related project context. Your job is to produce a focused briefing that identifies: relevant history, files to examine, implementation approach, traps, and test plan.
|
|
17
|
-
|
|
18
|
-
## Rules
|
|
19
|
-
- File paths must reference actual files from the context provided
|
|
20
|
-
- Cite related issues by number (#NNN) when relevant
|
|
21
|
-
- Identify edge cases the issue description doesn't mention
|
|
22
|
-
- Be concise — this is a briefing, not a full proposal
|
|
23
|
-
- When multiple approaches exist, list trade-offs with a clear recommendation
|
|
24
|
-
|
|
25
|
-
## Output Format
|
|
26
|
-
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
27
|
-
|
|
28
|
-
### Problem
|
|
29
|
-
[1-2 sentences restating the issue in concrete implementation terms. What exactly needs to change?]
|
|
30
|
-
|
|
31
|
-
### Historical Context
|
|
32
|
-
[Relevant sessions, PRs, decisions, related issues from the provided Totem knowledge. If nothing relevant, say "None found in provided context."]
|
|
33
|
-
|
|
34
|
-
### Files to Examine
|
|
35
|
-
[Ordered list of files the developer should read before starting. Most critical first. Format: \`path/to/file.ts\` — reason to examine]
|
|
36
|
-
|
|
37
|
-
### Approach
|
|
38
|
-
[Recommended implementation approach. Concrete steps, not abstract descriptions. If multiple valid approaches exist, list them as Option A / Option B with trade-offs and a clear recommendation.]
|
|
39
|
-
|
|
40
|
-
### Edge Cases & Traps
|
|
41
|
-
[Things the issue description doesn't mention but the developer should watch for. Include existing patterns that MUST be followed for consistency and potential regressions in related features.]
|
|
42
|
-
|
|
43
|
-
### Test Plan
|
|
44
|
-
[Specific test scenarios. Reference existing test file patterns when applicable.]
|
|
45
|
-
|
|
46
|
-
### Related Issues
|
|
47
|
-
[Issues that might be affected by or related to this work. Format: #NNN — title — relationship (blocks, unblocks, overlaps, conflicts). If none found, say "None identified."]
|
|
10
|
+
const SYSTEM_PROMPT = `# Spec System Prompt — Pre-Work Briefing
|
|
11
|
+
|
|
12
|
+
## Purpose
|
|
13
|
+
Produce a structured pre-work briefing for a GitHub issue before implementation begins.
|
|
14
|
+
|
|
15
|
+
## Role
|
|
16
|
+
You are a technical spec writer analyzing a GitHub issue and its related project context. Your job is to produce a focused briefing that identifies: relevant history, files to examine, implementation approach, traps, and test plan.
|
|
17
|
+
|
|
18
|
+
## Rules
|
|
19
|
+
- File paths must reference actual files from the context provided
|
|
20
|
+
- Cite related issues by number (#NNN) when relevant
|
|
21
|
+
- Identify edge cases the issue description doesn't mention
|
|
22
|
+
- Be concise — this is a briefing, not a full proposal
|
|
23
|
+
- When multiple approaches exist, list trade-offs with a clear recommendation
|
|
24
|
+
|
|
25
|
+
## Output Format
|
|
26
|
+
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
27
|
+
|
|
28
|
+
### Problem
|
|
29
|
+
[1-2 sentences restating the issue in concrete implementation terms. What exactly needs to change?]
|
|
30
|
+
|
|
31
|
+
### Historical Context
|
|
32
|
+
[Relevant sessions, PRs, decisions, related issues from the provided Totem knowledge. If nothing relevant, say "None found in provided context."]
|
|
33
|
+
|
|
34
|
+
### Files to Examine
|
|
35
|
+
[Ordered list of files the developer should read before starting. Most critical first. Format: \`path/to/file.ts\` — reason to examine]
|
|
36
|
+
|
|
37
|
+
### Approach
|
|
38
|
+
[Recommended implementation approach. Concrete steps, not abstract descriptions. If multiple valid approaches exist, list them as Option A / Option B with trade-offs and a clear recommendation.]
|
|
39
|
+
|
|
40
|
+
### Edge Cases & Traps
|
|
41
|
+
[Things the issue description doesn't mention but the developer should watch for. Include existing patterns that MUST be followed for consistency and potential regressions in related features.]
|
|
42
|
+
|
|
43
|
+
### Test Plan
|
|
44
|
+
[Specific test scenarios. Reference existing test file patterns when applicable.]
|
|
45
|
+
|
|
46
|
+
### Related Issues
|
|
47
|
+
[Issues that might be affected by or related to this work. Format: #NNN — title — relationship (blocks, unblocks, overlaps, conflicts). If none found, say "None identified."]
|
|
48
48
|
`;
|
|
49
49
|
// ─── GitHub helpers ─────────────────────────────────────
|
|
50
50
|
const GhIssueSchema = z.object({
|
package/dist/commands/triage.js
CHANGED
|
@@ -10,36 +10,36 @@ const MAX_SESSION_RESULTS = 5;
|
|
|
10
10
|
const QUERY_TITLES_TRUNCATE = 2_000;
|
|
11
11
|
const GH_ISSUE_LIMIT = 100;
|
|
12
12
|
// ─── System prompt ──────────────────────────────────────
|
|
13
|
-
const SYSTEM_PROMPT = `# Triage System Prompt — Active Work Roadmap
|
|
14
|
-
|
|
15
|
-
## Purpose
|
|
16
|
-
Produce a prioritized roadmap from the project's open GitHub issues, informed by recent work history from Totem knowledge.
|
|
17
|
-
|
|
18
|
-
## Role
|
|
19
|
-
You are a technical project manager analyzing a project's open issue backlog alongside its recent development history. Your job is to produce a clear, actionable prioritization that helps the developer decide what to work on next.
|
|
20
|
-
|
|
21
|
-
## Rules
|
|
22
|
-
- Reference issues by number (#NNN) and title
|
|
23
|
-
- Consider labels (bug, enhancement, priority, etc.) as strong signals
|
|
24
|
-
- Use recent session history and specs to understand project momentum — what was just finished, what's in progress
|
|
25
|
-
- Factor in issue age (updatedAt) — stale issues may need re-evaluation
|
|
26
|
-
- Be opinionated — give a clear recommendation, not a wishy-washy list
|
|
27
|
-
- Be concise — this is a decision-making tool, not a project plan
|
|
28
|
-
|
|
29
|
-
## Output Format
|
|
30
|
-
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
31
|
-
|
|
32
|
-
### Active Work Summary
|
|
33
|
-
[1-3 sentences about what was recently completed or is in progress, based on the Totem knowledge provided. If no relevant history, say "No recent session history available."]
|
|
34
|
-
|
|
35
|
-
### Prioritized Roadmap
|
|
36
|
-
[Ordered list of open issues, most important first. For each: #NNN — title — 1-sentence rationale for its priority position. Group by priority tier if helpful (e.g., "Do Next", "Up Next", "Backlog").]
|
|
37
|
-
|
|
38
|
-
### Next Issue
|
|
39
|
-
[Single recommended issue to work on next. Include: issue number, title, and 2-3 sentences explaining WHY this should be next — considering dependencies, momentum, and impact.]
|
|
40
|
-
|
|
41
|
-
### Blocked / Needs Input
|
|
42
|
-
[Issues that cannot progress without external input, decisions, or prerequisite work. If none, say "None identified."]
|
|
13
|
+
const SYSTEM_PROMPT = `# Triage System Prompt — Active Work Roadmap
|
|
14
|
+
|
|
15
|
+
## Purpose
|
|
16
|
+
Produce a prioritized roadmap from the project's open GitHub issues, informed by recent work history from Totem knowledge.
|
|
17
|
+
|
|
18
|
+
## Role
|
|
19
|
+
You are a technical project manager analyzing a project's open issue backlog alongside its recent development history. Your job is to produce a clear, actionable prioritization that helps the developer decide what to work on next.
|
|
20
|
+
|
|
21
|
+
## Rules
|
|
22
|
+
- Reference issues by number (#NNN) and title
|
|
23
|
+
- Consider labels (bug, enhancement, priority, etc.) as strong signals
|
|
24
|
+
- Use recent session history and specs to understand project momentum — what was just finished, what's in progress
|
|
25
|
+
- Factor in issue age (updatedAt) — stale issues may need re-evaluation
|
|
26
|
+
- Be opinionated — give a clear recommendation, not a wishy-washy list
|
|
27
|
+
- Be concise — this is a decision-making tool, not a project plan
|
|
28
|
+
|
|
29
|
+
## Output Format
|
|
30
|
+
Respond with ONLY the sections below. No preamble, no closing remarks.
|
|
31
|
+
|
|
32
|
+
### Active Work Summary
|
|
33
|
+
[1-3 sentences about what was recently completed or is in progress, based on the Totem knowledge provided. If no relevant history, say "No recent session history available."]
|
|
34
|
+
|
|
35
|
+
### Prioritized Roadmap
|
|
36
|
+
[Ordered list of open issues, most important first. For each: #NNN — title — 1-sentence rationale for its priority position. Group by priority tier if helpful (e.g., "Do Next", "Up Next", "Backlog").]
|
|
37
|
+
|
|
38
|
+
### Next Issue
|
|
39
|
+
[Single recommended issue to work on next. Include: issue number, title, and 2-3 sentences explaining WHY this should be next — considering dependencies, momentum, and impact.]
|
|
40
|
+
|
|
41
|
+
### Blocked / Needs Input
|
|
42
|
+
[Issues that cannot progress without external input, decisions, or prerequisite work. If none, say "None identified."]
|
|
43
43
|
`;
|
|
44
44
|
// ─── GitHub helpers ─────────────────────────────────────
|
|
45
45
|
const GhIssueListItemSchema = z.object({
|
package/dist/index.js
CHANGED
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,51 +1,51 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@mmnto/cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "CLI for Totem — AI persistent memory and context layer",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"totem": "./dist/index.js"
|
|
8
|
-
},
|
|
9
|
-
"main": "./dist/index.js",
|
|
10
|
-
"types": "./dist/index.d.ts",
|
|
11
|
-
"exports": {
|
|
12
|
-
".": {
|
|
13
|
-
"import": "./dist/index.js",
|
|
14
|
-
"types": "./dist/index.d.ts"
|
|
15
|
-
}
|
|
16
|
-
},
|
|
17
|
-
"
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
"
|
|
21
|
-
"
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
"
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
"
|
|
29
|
-
|
|
30
|
-
"
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
"
|
|
36
|
-
|
|
37
|
-
"
|
|
38
|
-
"
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
"
|
|
43
|
-
},
|
|
44
|
-
"
|
|
45
|
-
|
|
46
|
-
"
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
"
|
|
50
|
-
}
|
|
51
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@mmnto/cli",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "CLI for Totem — AI persistent memory and context layer",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"totem": "./dist/index.js"
|
|
8
|
+
},
|
|
9
|
+
"main": "./dist/index.js",
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"exports": {
|
|
12
|
+
".": {
|
|
13
|
+
"import": "./dist/index.js",
|
|
14
|
+
"types": "./dist/index.d.ts"
|
|
15
|
+
}
|
|
16
|
+
},
|
|
17
|
+
"dependencies": {
|
|
18
|
+
"commander": "^13.1.0",
|
|
19
|
+
"jiti": "^2.4.0",
|
|
20
|
+
"zod": "^3.24.0",
|
|
21
|
+
"@mmnto/totem": "0.2.0"
|
|
22
|
+
},
|
|
23
|
+
"devDependencies": {
|
|
24
|
+
"@types/node": "^22.0.0",
|
|
25
|
+
"typescript": "^5.7.0"
|
|
26
|
+
},
|
|
27
|
+
"files": [
|
|
28
|
+
"dist"
|
|
29
|
+
],
|
|
30
|
+
"license": "MIT",
|
|
31
|
+
"author": "mmnto-ai",
|
|
32
|
+
"repository": {
|
|
33
|
+
"type": "git",
|
|
34
|
+
"url": "https://github.com/mmnto-ai/totem.git",
|
|
35
|
+
"directory": "packages/cli"
|
|
36
|
+
},
|
|
37
|
+
"homepage": "https://github.com/mmnto-ai/totem",
|
|
38
|
+
"bugs": {
|
|
39
|
+
"url": "https://github.com/mmnto-ai/totem/issues"
|
|
40
|
+
},
|
|
41
|
+
"publishConfig": {
|
|
42
|
+
"access": "public"
|
|
43
|
+
},
|
|
44
|
+
"scripts": {
|
|
45
|
+
"build": "tsc",
|
|
46
|
+
"dev": "tsc --watch",
|
|
47
|
+
"clean": "rm -rf dist",
|
|
48
|
+
"lint": "eslint src/",
|
|
49
|
+
"test": "echo \"No tests yet\" && exit 0"
|
|
50
|
+
}
|
|
51
|
+
}
|