oh-my-customcode 0.105.1 → 0.106.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/README.md +6 -6
- package/dist/cli/index.js +1 -1
- package/dist/index.js +1 -1
- package/package.json +1 -1
- package/templates/.claude/agents/tracker-checkpoint.md +72 -0
- package/templates/.claude/skills/dag-orchestration/SKILL.md +46 -3
- package/templates/.claude/skills/pipeline-guards/SKILL.md +39 -0
- package/templates/.claude/skills/sdd-dev/SKILL.md +17 -3
- package/templates/.claude/skills/sdd-dev/templates/decision-record.md +45 -0
- package/templates/CLAUDE.md +6 -5
- package/templates/guides/agent-design/ralph-loop-pattern.md +32 -0
- package/templates/guides/claude-code/14-token-efficiency.md +45 -2
- package/templates/guides/harness-engineering/README.md +3 -3
- package/templates/manifest.json +4 -4
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
|
|
14
14
|
**[한국어 문서 (Korean)](./README_ko.md)**
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
49 agents. 113 skills. 22 rules. One command.
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
npm install -g oh-my-customcode && cd your-project && omcustom init
|
|
@@ -111,7 +111,7 @@ Agent(arch-documenter):haiku ┘
|
|
|
111
111
|
|
|
112
112
|
---
|
|
113
113
|
|
|
114
|
-
### Agents (
|
|
114
|
+
### Agents (49)
|
|
115
115
|
|
|
116
116
|
| Category | Count | Agents |
|
|
117
117
|
|----------|-------|--------|
|
|
@@ -126,7 +126,7 @@ Agent(arch-documenter):haiku ┘
|
|
|
126
126
|
| QA | 3 | qa-planner, qa-writer, qa-engineer |
|
|
127
127
|
| Security | 1 | sec-codeql |
|
|
128
128
|
| Managers | 6 | mgr-creator, mgr-updater, mgr-supplier, mgr-gitnerd, mgr-sauron, mgr-claude-code-bible |
|
|
129
|
-
| System |
|
|
129
|
+
| System | 3 | sys-memory-keeper, sys-naggy, tracker-checkpoint |
|
|
130
130
|
|
|
131
131
|
Each agent declares its tools, model, memory scope, and limitations in YAML frontmatter. Tool budgets are enforced per agent type for accuracy.
|
|
132
132
|
|
|
@@ -222,7 +222,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
|
|
|
222
222
|
|
|
223
223
|
---
|
|
224
224
|
|
|
225
|
-
### Guides (
|
|
225
|
+
### Guides (43)
|
|
226
226
|
|
|
227
227
|
Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
|
|
228
228
|
|
|
@@ -271,7 +271,7 @@ omcustom serve-stop # Stop Web UI
|
|
|
271
271
|
your-project/
|
|
272
272
|
├── CLAUDE.md # Entry point
|
|
273
273
|
├── .claude/
|
|
274
|
-
│ ├── agents/ #
|
|
274
|
+
│ ├── agents/ # 49 agent definitions
|
|
275
275
|
│ ├── skills/ # 113 skill modules
|
|
276
276
|
│ ├── rules/ # 22 governance rules (R000-R021)
|
|
277
277
|
│ ├── hooks/ # 15 lifecycle hook scripts
|
|
@@ -279,7 +279,7 @@ your-project/
|
|
|
279
279
|
│ ├── specs/ # Extracted canonical specs
|
|
280
280
|
│ ├── contexts/ # 4 shared context files
|
|
281
281
|
│ └── ontology/ # Knowledge graph for RAG
|
|
282
|
-
└── guides/ #
|
|
282
|
+
└── guides/ # 43 reference documents
|
|
283
283
|
```
|
|
284
284
|
|
|
285
285
|
---
|
package/dist/cli/index.js
CHANGED
package/dist/index.js
CHANGED
package/package.json
CHANGED
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tracker-checkpoint
|
|
3
|
+
description: Pipeline execution state tracker with checkpoint persistence. Reads/writes /tmp/.claude-pipeline-*-{PPID}.json state files and validates state transitions. Used by dag-orchestration for resume-after-failure and pipeline-guards for quality gate state.
|
|
4
|
+
model: sonnet
|
|
5
|
+
effort: medium
|
|
6
|
+
tools: [Read, Write, Edit, Bash, Glob, Grep]
|
|
7
|
+
memory: project
|
|
8
|
+
skills: [dag-orchestration, pipeline-guards]
|
|
9
|
+
domain: universal
|
|
10
|
+
permissionMode: bypassPermissions
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Tracker Checkpoint Agent
|
|
14
|
+
|
|
15
|
+
## Purpose
|
|
16
|
+
|
|
17
|
+
Pipeline 실행 상태를 persistent checkpoint 파일로 관리. `/pipeline resume`, `dag-orchestration`, `pipeline-guards`와 협력하여 실패 후 재개를 가능하게 합니다.
|
|
18
|
+
|
|
19
|
+
## Capabilities
|
|
20
|
+
|
|
21
|
+
- Read/write `/tmp/.claude-pipeline-{name}-{PPID}.json` state files
|
|
22
|
+
- Validate state transitions (pending → running → completed | failed)
|
|
23
|
+
- Coordinate with dag-orchestration for step-level checkpointing
|
|
24
|
+
- Coordinate with pipeline-guards for gate-level state snapshots
|
|
25
|
+
- Support `/pipeline resume` by loading last known state
|
|
26
|
+
|
|
27
|
+
## Workflow
|
|
28
|
+
|
|
29
|
+
### 1. Pipeline Start (Bootstrap)
|
|
30
|
+
- Create `/tmp/.claude-pipeline-{name}-{PPID}.json` with initial state
|
|
31
|
+
- Record: pipeline name, started timestamp, total steps, current_step=0
|
|
32
|
+
|
|
33
|
+
### 2. Per-Step Checkpoint
|
|
34
|
+
- After each step: update state file atomically
|
|
35
|
+
- Record: step name, status, duration_ms, output artifacts paths
|
|
36
|
+
- Status transitions: pending → running → completed | failed
|
|
37
|
+
|
|
38
|
+
### 3. Failure Freeze
|
|
39
|
+
- On step failure: mark status=halted, preserve state for resume
|
|
40
|
+
- Capture: error message, stack trace (if any), partial artifacts
|
|
41
|
+
|
|
42
|
+
### 4. Resume Coordination
|
|
43
|
+
- On `/pipeline resume`: scan `/tmp/.claude-pipeline-*-{PPID}.json`
|
|
44
|
+
- Return state to orchestrator: name, failed step, error, options (retry/skip/abort)
|
|
45
|
+
- On retry: reset failed step to pending, resume execution
|
|
46
|
+
|
|
47
|
+
## State File Schema
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"pipeline": "{name}",
|
|
52
|
+
"started": "ISO-8601",
|
|
53
|
+
"status": "running|completed|halted",
|
|
54
|
+
"current_step": 0,
|
|
55
|
+
"steps": [
|
|
56
|
+
{"name": "triage", "status": "completed", "duration_ms": 5000, "artifacts": []},
|
|
57
|
+
{"name": "plan", "status": "running"}
|
|
58
|
+
]
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Integration Points
|
|
63
|
+
|
|
64
|
+
- `dag-orchestration` skill — step dependency resolution + tracker coordination
|
|
65
|
+
- `pipeline-guards` skill — guard gate state preservation
|
|
66
|
+
- `pipeline` skill — `/pipeline resume` state loader
|
|
67
|
+
|
|
68
|
+
## Rules Compliance
|
|
69
|
+
|
|
70
|
+
- R006: Agent artifact; skills (dag-orchestration, pipeline-guards) are source
|
|
71
|
+
- R010: File modifications via Write/Edit (prefer over Bash for .claude/ paths)
|
|
72
|
+
- R017: Structural changes require sauron verification
|
|
@@ -57,7 +57,7 @@ nodes:
|
|
|
57
57
|
depends_on: [test, review, docs]
|
|
58
58
|
|
|
59
59
|
config:
|
|
60
|
-
max_parallel: 4 # R009
|
|
60
|
+
max_parallel: 4 # R009 soft default (hard cap: 5)
|
|
61
61
|
failure_strategy: stop # stop | skip | retry
|
|
62
62
|
retry_count: 2 # Max retries per node (if strategy=retry)
|
|
63
63
|
timeout_per_node: 300 # Seconds per node (0 = no limit)
|
|
@@ -76,7 +76,11 @@ config:
|
|
|
76
76
|
c. On completion:
|
|
77
77
|
- Success → decrement in-degree of dependents
|
|
78
78
|
- Failure → apply failure_strategy
|
|
79
|
-
d.
|
|
79
|
+
d. Stall check:
|
|
80
|
+
- If running node duration > 2x average completed duration
|
|
81
|
+
- AND pending nodes exist with in-degree = 0 (ignoring stalled node's edges)
|
|
82
|
+
- THEN enqueue those independent nodes immediately (adaptive split)
|
|
83
|
+
e. Enqueue newly-ready nodes (in-degree = 0)
|
|
80
84
|
6. Verify all nodes executed (detect unreachable nodes)
|
|
81
85
|
```
|
|
82
86
|
|
|
@@ -84,11 +88,12 @@ config:
|
|
|
84
88
|
|
|
85
89
|
| Rule | Detail |
|
|
86
90
|
|------|--------|
|
|
87
|
-
| Max parallel |
|
|
91
|
+
| Max parallel | 5 concurrent nodes max, 4 default (R009) |
|
|
88
92
|
| Agent Teams gate | 3+ parallel nodes → check R018 eligibility |
|
|
89
93
|
| Orchestrator only | DAG scheduling runs in main conversation (R010) |
|
|
90
94
|
| Node execution | Each node = one Task tool call to specified agent |
|
|
91
95
|
| State tracking | `/tmp/.claude-dag-$PPID.json` |
|
|
96
|
+
| Stall detection | Running node > 2x avg completed duration → enqueue independent pending nodes early |
|
|
92
97
|
|
|
93
98
|
## Failure Strategies
|
|
94
99
|
|
|
@@ -193,9 +198,47 @@ Execute? [Y/n]
|
|
|
193
198
|
|
|
194
199
|
The orchestrator builds the DAG from this inline format and executes using the same algorithm.
|
|
195
200
|
|
|
201
|
+
## State Management via tracker-checkpoint
|
|
202
|
+
|
|
203
|
+
Pipeline 상태는 `tracker-checkpoint` 에이전트로 위임됩니다.
|
|
204
|
+
|
|
205
|
+
### Flow
|
|
206
|
+
|
|
207
|
+
1. Pipeline 시작 → orchestrator가 tracker-checkpoint 호출 → 초기 state 파일 생성 (`/tmp/.claude-pipeline-{name}-{PPID}.json`)
|
|
208
|
+
2. 각 step 후 → tracker-checkpoint가 state 업데이트 (atomic write)
|
|
209
|
+
3. step 실패 → tracker-checkpoint가 halted 상태로 freeze
|
|
210
|
+
4. `/pipeline resume` → tracker-checkpoint가 state 로드 → orchestrator에 복원 옵션 제공
|
|
211
|
+
|
|
212
|
+
### Integration
|
|
213
|
+
|
|
214
|
+
- PPID-scoped state file 경로: `/tmp/.claude-pipeline-{name}-{PPID}.json`
|
|
215
|
+
- step 실행 전후로 tracker-checkpoint delegation
|
|
216
|
+
- resume 시 checkpoint → dag 재빌드 → 미완료 step부터 재개
|
|
217
|
+
|
|
218
|
+
See `.claude/agents/tracker-checkpoint.md` for agent spec.
|
|
219
|
+
|
|
196
220
|
## Limitations
|
|
197
221
|
|
|
198
222
|
- No cycles allowed (DAG = acyclic)
|
|
199
223
|
- Max 20 nodes per workflow (complexity guard)
|
|
200
224
|
- Nested DAGs not supported (flatten instead)
|
|
201
225
|
- Cross-workflow dependencies not supported
|
|
226
|
+
|
|
227
|
+
## External References
|
|
228
|
+
|
|
229
|
+
### Multica — Managed Agent Platform
|
|
230
|
+
|
|
231
|
+
> Reference: [Multica](https://github.com/multica-ai/multica) — managed agent platform for Claude Code/Codex.
|
|
232
|
+
> Verdict: INTEGRATE (external reference, not internalize)
|
|
233
|
+
|
|
234
|
+
Multica's task lifecycle pattern (enqueue → claim → start → complete/fail) is a useful reference for DAG node state management:
|
|
235
|
+
|
|
236
|
+
| Multica State | DAG Equivalent | Notes |
|
|
237
|
+
|---------------|---------------|-------|
|
|
238
|
+
| enqueue | pending | Node waiting for dependencies |
|
|
239
|
+
| claim | ready | Dependencies resolved, ready to execute |
|
|
240
|
+
| start | running | Agent spawned and executing |
|
|
241
|
+
| complete | completed | Node finished successfully |
|
|
242
|
+
| fail | failed | Node execution failed |
|
|
243
|
+
|
|
244
|
+
Consider this pattern when extending DAG node state tracking or implementing retry logic.
|
|
@@ -19,11 +19,13 @@ Defines mandatory safety constraints for all pipeline, workflow, and iterative e
|
|
|
19
19
|
| Max iterations | 3 | 5 | worker-reviewer-pipeline |
|
|
20
20
|
| Max DAG nodes | 20 | 30 | dag-orchestration |
|
|
21
21
|
| Max parallel agents | 4 | 5 | R009 (all pipelines) |
|
|
22
|
+
| Max parallel steps | 4 | 4 | pipeline parallel blocks |
|
|
22
23
|
| Timeout per node | 300s | 600s | dag-orchestration nodes |
|
|
23
24
|
| Timeout per pipeline | 900s | 1800s | worker-reviewer-pipeline |
|
|
24
25
|
| Max retry count | 2 | 3 | Failure retry strategies |
|
|
25
26
|
| Max PR improvement items | 20 | 50 | pr-auto-improve |
|
|
26
27
|
| Max auto-improve items | 20 | 50 | omcustom-auto-improve |
|
|
28
|
+
| Max files per agent | 10 | 15 | All agent spawns (advisory) |
|
|
27
29
|
|
|
28
30
|
## Enforcement
|
|
29
31
|
|
|
@@ -82,6 +84,23 @@ When guards are triggered, they integrate with existing advisory systems:
|
|
|
82
84
|
| Timeout approaching (80%) | → warn user, suggest early termination |
|
|
83
85
|
| Hard cap hit | → force stop, report to user |
|
|
84
86
|
|
|
87
|
+
## Task Granularity Guard
|
|
88
|
+
|
|
89
|
+
Advisory guard for agent task scope. When a single agent is assigned too many files, it becomes a bottleneck in parallel execution.
|
|
90
|
+
|
|
91
|
+
| Signal | Default | Action |
|
|
92
|
+
|--------|---------|--------|
|
|
93
|
+
| Files per agent > 10 | Advisory warning | Suggest splitting by layer/domain |
|
|
94
|
+
| Files per agent > 15 | Hard warning | Require explicit user override |
|
|
95
|
+
|
|
96
|
+
Display:
|
|
97
|
+
```
|
|
98
|
+
[Guard] ⚠ Agent assigned {n} files (> 10) — consider splitting by layer
|
|
99
|
+
[Guard] 🛑 Agent assigned {n} files (> 15) — requires explicit override
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
This integrates with R009 Adaptive Parallel Splitting: if a stalled agent is detected AND it was assigned > 10 files, the splitting recommendation is stronger.
|
|
103
|
+
|
|
85
104
|
## Guard Configuration
|
|
86
105
|
|
|
87
106
|
Pipelines can override defaults (within hard caps):
|
|
@@ -157,6 +176,26 @@ Guard warnings appear inline:
|
|
|
157
176
|
| omcustom-auto-improve | Auto-improve item count limits |
|
|
158
177
|
| stuck-recovery | Guard triggers feed into stuck detection |
|
|
159
178
|
| model-escalation | Repeated failures trigger escalation advisory |
|
|
179
|
+
| task-decomposition | Subtask file counts validated against granularity guard thresholds |
|
|
180
|
+
|
|
181
|
+
## Checkpoint Gate Integration
|
|
182
|
+
|
|
183
|
+
각 guard 통과/실패 시 `tracker-checkpoint` 에이전트로 gate state 기록.
|
|
184
|
+
|
|
185
|
+
### Flow
|
|
186
|
+
|
|
187
|
+
1. Guard 진입 → tracker-checkpoint에 gate state: running 기록
|
|
188
|
+
2. Guard 통과 → tracker-checkpoint에 gate state: passed + metrics 기록
|
|
189
|
+
3. Guard 실패 → tracker-checkpoint에 gate state: failed + failure reason freeze
|
|
190
|
+
4. 다음 단계는 checkpoint state 참조하여 재개/중단 판단
|
|
191
|
+
|
|
192
|
+
### Benefits
|
|
193
|
+
|
|
194
|
+
- 긴 파이프라인에서 guard 지점마다 복원점 확보
|
|
195
|
+
- 부분 실패 시 직전 guard 지점부터 재시도 가능 (비용 절감)
|
|
196
|
+
- guard metrics 축적으로 품질 추이 관찰 가능
|
|
197
|
+
|
|
198
|
+
See `.claude/agents/tracker-checkpoint.md` for the tracker spec.
|
|
160
199
|
|
|
161
200
|
## Override Policy
|
|
162
201
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: sdd-dev
|
|
3
3
|
description: Spec-Driven Development workflow — enforces sdd/ folder hierarchy with planning-first gates, current-state artifacts, and completion verification
|
|
4
4
|
scope: core
|
|
5
|
-
version: 1.
|
|
5
|
+
version: 1.1.0
|
|
6
6
|
user-invocable: true
|
|
7
7
|
argument-hint: "[task description or leave empty for guided workflow]"
|
|
8
8
|
---
|
|
@@ -27,7 +27,8 @@ sdd/
|
|
|
27
27
|
├── 03_build/ # Current build state, implementation notes
|
|
28
28
|
├── 04_verify/ # Verification evidence, test results, residual risks
|
|
29
29
|
├── 05_operate/ # Deployment notes, runbooks (conditional)
|
|
30
|
-
|
|
30
|
+
├── 99_toolchain/ # Tool configs, scripts, environment setup
|
|
31
|
+
└── decisions/ # Decision records for major design choices
|
|
31
32
|
```
|
|
32
33
|
|
|
33
34
|
**Key Principle**: These folders are **current-state artifacts**, not history archives. Each file reflects the current state of the work — update in place rather than appending new versions.
|
|
@@ -44,7 +45,7 @@ ls sdd/ 2>/dev/null || echo "sdd/ folder not found"
|
|
|
44
45
|
|
|
45
46
|
If `sdd/` does not exist:
|
|
46
47
|
1. Inform the user that SDD workflow requires a `sdd/` folder
|
|
47
|
-
2. Offer to create the folder structure: `mkdir -p sdd/{01_planning,02_plan,03_build,04_verify,05_operate,99_toolchain}`
|
|
48
|
+
2. Offer to create the folder structure: `mkdir -p sdd/{01_planning,02_plan,03_build,04_verify,05_operate,99_toolchain,decisions}`
|
|
48
49
|
3. Ask user to confirm before proceeding
|
|
49
50
|
|
|
50
51
|
If `sdd/` exists, continue to Step 1.
|
|
@@ -121,6 +122,7 @@ Artifact to produce or update: `sdd/03_build/current.md`
|
|
|
121
122
|
|
|
122
123
|
## Decisions Made
|
|
123
124
|
- {decision}: {rationale}
|
|
125
|
+
- Write DR for major decisions: sdd/decisions/{YYYY-MM-DD}-{topic}.md (template: templates/decision-record.md)
|
|
124
126
|
|
|
125
127
|
## Known Issues
|
|
126
128
|
- {issue}: {planned resolution}
|
|
@@ -235,6 +237,18 @@ Final display:
|
|
|
235
237
|
3. **Checkboxes reflect reality**: Do NOT pre-check criteria. Update checkboxes as work is verified.
|
|
236
238
|
4. **Residual risks are honest**: List known risks even after passing. Hiding risks defeats the purpose.
|
|
237
239
|
|
|
240
|
+
## Decision Record Template
|
|
241
|
+
|
|
242
|
+
Major design decisions during Step 3 are recorded in `sdd/decisions/{YYYY-MM-DD}-{topic}.md` using the template at `templates/decision-record.md` (relative to this skill directory).
|
|
243
|
+
|
|
244
|
+
When to create a Decision Record:
|
|
245
|
+
- Architectural choice between 2+ viable options
|
|
246
|
+
- Trade-off accepted (e.g., complexity for performance)
|
|
247
|
+
- Deferred decision (waiting for data/approval)
|
|
248
|
+
- Superseding a previous decision
|
|
249
|
+
|
|
250
|
+
See `guides/harness-engineering/` for harness-level decision context that DRs may reference.
|
|
251
|
+
|
|
238
252
|
## Integration with Other Skills
|
|
239
253
|
|
|
240
254
|
| Skill | When to Use Together |
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: {Decision title}
|
|
3
|
+
date: YYYY-MM-DD
|
|
4
|
+
status: proposed | accepted | superseded | deprecated
|
|
5
|
+
context: guides/harness-engineering/README.md
|
|
6
|
+
decision_makers: [{agent or role}]
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# {Decision title}
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
|
|
13
|
+
{What is the problem and why is a decision needed? Include relevant constraints, goals, and the situation that makes this decision necessary.}
|
|
14
|
+
|
|
15
|
+
## Options Considered
|
|
16
|
+
|
|
17
|
+
1. **Option A**: {Description}
|
|
18
|
+
- Pros: {benefits}
|
|
19
|
+
- Cons: {drawbacks, trade-offs}
|
|
20
|
+
|
|
21
|
+
2. **Option B**: {Description}
|
|
22
|
+
- Pros: {benefits}
|
|
23
|
+
- Cons: {drawbacks, trade-offs}
|
|
24
|
+
|
|
25
|
+
3. **Option C** *(if applicable)*: {Description}
|
|
26
|
+
- Pros: {benefits}
|
|
27
|
+
- Cons: {drawbacks, trade-offs}
|
|
28
|
+
|
|
29
|
+
## Decision
|
|
30
|
+
|
|
31
|
+
**Chosen**: Option {A|B|C}
|
|
32
|
+
|
|
33
|
+
{Explain the rationale for the choice. Why does this option best satisfy the constraints and goals from the Context section?}
|
|
34
|
+
|
|
35
|
+
## Consequences
|
|
36
|
+
|
|
37
|
+
- **Positive**: {What improves as a result of this decision}
|
|
38
|
+
- **Negative**: {Trade-offs and costs accepted}
|
|
39
|
+
- **Risks**: {Future considerations, potential issues to monitor}
|
|
40
|
+
|
|
41
|
+
## References
|
|
42
|
+
|
|
43
|
+
- guides/harness-engineering/README.md
|
|
44
|
+
- {related skill or agent, e.g. .claude/skills/action-validator/SKILL.md}
|
|
45
|
+
- {link to issue or PR if applicable}
|
package/templates/CLAUDE.md
CHANGED
|
@@ -103,7 +103,7 @@ oh-my-customcode로 구동됩니다.
|
|
|
103
103
|
| 릴리즈 | `/pipeline auto-dev`, `/omcustom-release-notes`, `/release-plan` | 자동 개발, 릴리즈 노트 |
|
|
104
104
|
| 리서치 | `/research`, `/scout`, `/deep-plan`, `/omcustom:agora` | 병렬 분석, URL 평가, 연구 계획 |
|
|
105
105
|
| 메모리 | `/memory-save`, `/memory-recall` | 세션 메모리 관리 |
|
|
106
|
-
| 최적화 | `/token-efficiency-audit` | 토큰 효율 감사 (
|
|
106
|
+
| 최적화 | `/token-efficiency-audit` | 토큰 효율 감사 (5계층 방어 스택) |
|
|
107
107
|
| 시스템 | `/omcustom:lists`, `/omcustom:status`, `/omcustom:help` | 전체 목록, 상태, 도움말 |
|
|
108
108
|
|
|
109
109
|
> 전체 커맨드 목록 (60+ 커맨드): `/omcustom:lists` 실행
|
|
@@ -114,12 +114,12 @@ oh-my-customcode로 구동됩니다.
|
|
|
114
114
|
project/
|
|
115
115
|
+-- CLAUDE.md # 진입점
|
|
116
116
|
+-- .claude/
|
|
117
|
-
| +-- agents/ # 서브에이전트 정의 (
|
|
117
|
+
| +-- agents/ # 서브에이전트 정의 (49 파일)
|
|
118
118
|
| +-- skills/ # 스킬 (113 디렉토리)
|
|
119
119
|
| +-- rules/ # 전역 규칙 (R000-R022)
|
|
120
120
|
| +-- hooks/ # 훅 스크립트 (보안, 검증, HUD)
|
|
121
121
|
| +-- contexts/ # 컨텍스트 파일 (ecomode)
|
|
122
|
-
+-- guides/ # 레퍼런스 문서 (
|
|
122
|
+
+-- guides/ # 레퍼런스 문서 (43 토픽)
|
|
123
123
|
```
|
|
124
124
|
|
|
125
125
|
## 오케스트레이션
|
|
@@ -173,8 +173,8 @@ oh-my-customcode는 소프트웨어 컴파일과 동일한 구조를 따릅니
|
|
|
173
173
|
| Infra Engineer | 2 | infra-docker-expert, infra-aws-expert |
|
|
174
174
|
| QA Team | 3 | qa-planner, qa-writer, qa-engineer |
|
|
175
175
|
| Manager | 6 | mgr-creator, mgr-updater, mgr-supplier, mgr-gitnerd, mgr-sauron, mgr-claude-code-bible |
|
|
176
|
-
| System |
|
|
177
|
-
| **총계** | **
|
|
176
|
+
| System | 4 | sys-memory-keeper, sys-naggy, tracker-checkpoint, wiki-curator |
|
|
177
|
+
| **총계** | **49** | |
|
|
178
178
|
|
|
179
179
|
## Agent Teams (MUST when enabled)
|
|
180
180
|
|
|
@@ -236,6 +236,7 @@ Claude Code의 Agent Teams 기능이 활성화되어 있으면 (`CLAUDE_CODE_EXP
|
|
|
236
236
|
| 플러그인 | 소스 | 용도 |
|
|
237
237
|
|----------|------|------|
|
|
238
238
|
| cc-token-saver | ww-w-ai/cc-token-saver | 토큰/비용 최적화 (Token Guardian, /continue, /usage-view) |
|
|
239
|
+
| caveman | JuliusBrussee/caveman | 영어 출력 토큰 압축 (코드 리뷰·커밋 메시지). R013 ecomode 미적용 구간 보완. 한국어 컨텍스트(R000)에는 ecomode 우선. `lite`/`full` 권장, `ultra`/`文言文` 가독성 저하 주의 |
|
|
239
240
|
|
|
240
241
|
### 권장 MCP 서버
|
|
241
242
|
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Ralph Loop Pattern — 세션 경계 지속 진화
|
|
2
|
+
|
|
3
|
+
> 출처: Q00/ouroboros Ralph Loop 패턴 (INTEGRATE #966)
|
|
4
|
+
> 도입일: v0.106.0
|
|
5
|
+
|
|
6
|
+
## Context
|
|
7
|
+
|
|
8
|
+
LLM 에이전트는 세션 종료 시 누적된 맥락(tacit knowledge, 실패 교훈, 선호 패턴)을 잃는다. Ralph Loop는 세션 간 경계를 넘는 지속 진화 메커니즘으로, 각 세션의 실패/성공 sticky patterns를 다음 세션의 초기 컨텍스트로 주입한다.
|
|
9
|
+
|
|
10
|
+
## Claude Code 통합
|
|
11
|
+
|
|
12
|
+
- **claude-mem MCP**: feedback memories + session archives를 영속 저장소로
|
|
13
|
+
- **sys-memory-keeper 에이전트**: 세션 종료 시 Ralph Loop 요약 수행
|
|
14
|
+
- **R011 Memory Integration**: native auto-memory를 Ralph Loop의 primary writer로
|
|
15
|
+
|
|
16
|
+
## Pattern
|
|
17
|
+
|
|
18
|
+
1. **Bootstrap**: 세션 시작 시 MEMORY.md에서 이전 Ralph Loop 요약 로드
|
|
19
|
+
2. **Evolve**: 세션 진행 중 발견한 새 패턴/실패를 feedback memory에 기록
|
|
20
|
+
3. **Compact**: 세션 종료 시 sys-memory-keeper가 Ralph Loop 요약을 MEMORY.md 업데이트
|
|
21
|
+
4. **Persist**: claude-mem MCP에 long-term save (cross-session search)
|
|
22
|
+
|
|
23
|
+
## Anti-patterns
|
|
24
|
+
|
|
25
|
+
- 세션마다 처음부터 다시 시작하는 sessionless 모드 (R011 native memory 사용)
|
|
26
|
+
- 모든 세션 로그를 저장하는 brute-force persistence (selective feedback만)
|
|
27
|
+
|
|
28
|
+
## References
|
|
29
|
+
|
|
30
|
+
- R011 SHOULD-memory-integration.md
|
|
31
|
+
- sys-memory-keeper 에이전트
|
|
32
|
+
- Q00/ouroboros `ooo interview/run/ralph` CLI
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# Token Efficiency —
|
|
1
|
+
# Token Efficiency — Five-Layer Defense Stack
|
|
2
2
|
|
|
3
3
|
> **Source**: [Claude Code & Codex token efficiency by settings adjustment](https://www.stdy.blog/increasing-token-efficiency-by-setting-adjustment-in-claude-and-codex/)
|
|
4
4
|
> **Reference baseline**: Claude Code v2.1.114+ / Codex v0.121.0+
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
|
|
8
8
|
Token spend in Claude Code is not purely a function of task complexity. A significant portion of token consumption occurs through structural overhead: auto-injected git instructions, IDE file listings, tool output that exceeds what the model actually needs, and session state reloaded unnecessarily across turns.
|
|
9
9
|
|
|
10
|
-
The
|
|
10
|
+
The five-layer defense stack addresses this overhead at distinct points in the session lifecycle:
|
|
11
11
|
|
|
12
12
|
```
|
|
13
13
|
┌─────────────────────────────────────────────────────────────────┐
|
|
@@ -22,6 +22,10 @@ The three-layer defense stack addresses this overhead at three distinct points i
|
|
|
22
22
|
├─────────────────────────────────────────────────────────────────┤
|
|
23
23
|
│ Layer 4: playwright-compress (MCP OUTPUT INTELLIGENCE) │
|
|
24
24
|
│ PostToolUse hook — Haiku summarization of browser MCP output │
|
|
25
|
+
├─────────────────────────────────────────────────────────────────┤
|
|
26
|
+
│ Layer 5: caveman (OUTPUT STYLE COMPRESSION) │
|
|
27
|
+
│ SessionStart hook — primitive-speech output reduces token spend│
|
|
28
|
+
│ English scenarios only — R000 Korean-first contexts use Layer 2│
|
|
25
29
|
└─────────────────────────────────────────────────────────────────┘
|
|
26
30
|
```
|
|
27
31
|
|
|
@@ -153,6 +157,7 @@ Disabling `includeGitInstructions` removes git workflow guidance from the contex
|
|
|
153
157
|
| R001 Safety | `apply-ci` mode is Risk Level High — requires user confirmation before applying. |
|
|
154
158
|
| R012 HUD Statusline | Statusline shows CTX% — effective measure of Layer 2+3 combined impact. |
|
|
155
159
|
| playwright-compress | Layer 4 hook — complements Layer 3 MAX_MCP_OUTPUT_TOKENS with intelligent lossless compression. |
|
|
160
|
+
| caveman | Layer 5 style compression — orthogonal to Layer 2 (volume) and Layer 4 (MCP). R000 Korean-first: use Layer 2 as primary. |
|
|
156
161
|
|
|
157
162
|
---
|
|
158
163
|
|
|
@@ -175,6 +180,43 @@ Hook trigger: `mcp__playwright__.*` and `mcp__claude-in-chrome__.*`
|
|
|
175
180
|
|
|
176
181
|
---
|
|
177
182
|
|
|
183
|
+
## Layer 5: caveman (Output Style Compression)
|
|
184
|
+
|
|
185
|
+
External plugin (JuliusBrussee/caveman, 41.6k stars, MIT) that rewrites Claude responses into compressed "primitive speech" via a SessionStart hook.
|
|
186
|
+
|
|
187
|
+
**Measured savings:**
|
|
188
|
+
- ~75% output token reduction
|
|
189
|
+
- ~46% input token reduction (context accumulation effect)
|
|
190
|
+
|
|
191
|
+
**Intensity levels:**
|
|
192
|
+
|
|
193
|
+
| Level | Description | Recommendation |
|
|
194
|
+
|-------|-------------|----------------|
|
|
195
|
+
| `lite` | Light compression, high readability | Recommended |
|
|
196
|
+
| `full` | Moderate compression | Recommended |
|
|
197
|
+
| `ultra` | Heavy compression, reduced readability | Caution |
|
|
198
|
+
| `文言文` | Classical Chinese style | Avoid for shared sessions |
|
|
199
|
+
|
|
200
|
+
**Installation:** `/plugin install caveman` (requires marketplace access)
|
|
201
|
+
|
|
202
|
+
**When to use:**
|
|
203
|
+
|
|
204
|
+
| Scenario | Layer to apply |
|
|
205
|
+
|----------|---------------|
|
|
206
|
+
| English-only output sessions (code review, commit messages) | Layer 5 (caveman) |
|
|
207
|
+
| Korean-first sessions (R000 contexts) | Layer 2 (R013 ecomode) — caveman articles/prepositions not present in Korean |
|
|
208
|
+
| Mixed sessions | Layer 2 primary, Layer 5 optional |
|
|
209
|
+
|
|
210
|
+
**Coexistence with other layers:**
|
|
211
|
+
|
|
212
|
+
- Layer 5 compresses output style; Layer 2 (ecomode) compresses output volume. These are orthogonal — both can be active simultaneously.
|
|
213
|
+
- Layer 5 applies globally to all responses; Layer 2 activates conditionally (4+ tasks threshold).
|
|
214
|
+
- For Korean-first projects following R000, Layer 2 provides the primary compression benefit. Layer 5's article-removal compression is largely ineffective against Korean (article-free language).
|
|
215
|
+
|
|
216
|
+
**R000 compatibility note:** caveman's compression relies on English grammatical structure (removing articles, prepositions). Korean lacks these structures, so compression rates are significantly lower in Korean-dominant sessions. Use `lite` or `full` mode only; avoid `ultra`/`文言文` in shared or multilingual sessions.
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
178
220
|
## Cross-References
|
|
179
221
|
|
|
180
222
|
- `guides/claude-code/13-cli-flags.md` — CLI flags for non-interactive/CI invocation
|
|
@@ -185,3 +227,4 @@ Hook trigger: `mcp__playwright__.*` and `mcp__claude-in-chrome__.*`
|
|
|
185
227
|
- `.claude/skills/update-config/` — Generic settings.json manipulation (broader scope)
|
|
186
228
|
- `.claude/skills/playwright-compress/SKILL.md` — Layer 4 MCP output compression hook
|
|
187
229
|
- `.claude/hooks/scripts/playwright-compress.sh` — Layer 4 hook script
|
|
230
|
+
- `https://github.com/JuliusBrussee/caveman` — Layer 5 caveman plugin (external)
|
|
@@ -46,9 +46,9 @@ Deep Insight가 제안하는 4계층 구조는 oh-my-customcode에 이미 구현
|
|
|
46
46
|
메인 대화 → Agent(mgr-creator, mode: "bypassPermissions") → Write(".claude/agents/new.md", content)
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
### Tracker 체크포인트 패턴
|
|
49
|
+
### Tracker 체크포인트 패턴
|
|
50
50
|
|
|
51
|
-
현재 파이프라인 상태 추적은 `/tmp/.claude-pipeline-{PID}.json` 파일과 `.claude/outputs/sessions/{YYYY-MM-DD}/` 아티팩트 규약으로 구현되어 있습니다. 전용 Tracker 에이전트(dag-orchestration / pipeline-guards 통합형)
|
|
51
|
+
현재 파이프라인 상태 추적은 `/tmp/.claude-pipeline-{PID}.json` 파일과 `.claude/outputs/sessions/{YYYY-MM-DD}/` 아티팩트 규약으로 구현되어 있습니다. ✅ 구현 완료 (v0.106.1 via #983 — `.claude/agents/tracker-checkpoint.md`): 전용 Tracker 에이전트(dag-orchestration / pipeline-guards 통합형)가 배포되어 checkpoint persistence, resume-after-failure, gate state 기록을 담당합니다.
|
|
52
52
|
|
|
53
53
|
---
|
|
54
54
|
|
|
@@ -185,7 +185,7 @@ opt-in: hard-enforce (filter 모드, --hard-enforce 플래그) — 명시적 사
|
|
|
185
185
|
|
|
186
186
|
| 항목 | 이관 이유 | 예상 릴리즈 |
|
|
187
187
|
|------|----------|-----------|
|
|
188
|
-
| **Tracker 체크포인트 에이전트** — dag-orchestration / pipeline-guards 통합형 전용 Tracker |
|
|
188
|
+
| **Tracker 체크포인트 에이전트** — dag-orchestration / pipeline-guards 통합형 전용 Tracker | ✅ 구현 완료 (v0.106.1 via #983 — `.claude/agents/tracker-checkpoint.md`) | — |
|
|
189
189
|
| **hierarchical-agent-topology 스킬** — 4계층 구조를 자동 검증하는 전용 스킬 | fork 스킬 cap 해소 후 추가 | v0.106.0+ |
|
|
190
190
|
| **sdd-dev Harness Decision Record 템플릿** — 하네스 설계 결정을 ADR 형식으로 기록 | sdd-dev 스킬 업데이트와 병행 | v0.107.0+ |
|
|
191
191
|
| **harness-synthesizer 2단계 격리 구현 예시** — Base64 인코딩 + subprocess 격리의 실제 YAML 예시 | 보안 리뷰 후 추가 | v0.107.0+ |
|
package/templates/manifest.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "0.
|
|
3
|
-
"lastUpdated": "2026-04-
|
|
2
|
+
"version": "0.106.1",
|
|
3
|
+
"lastUpdated": "2026-04-24T07:30:00.000Z",
|
|
4
4
|
"components": [
|
|
5
5
|
{
|
|
6
6
|
"name": "rules",
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"name": "agents",
|
|
13
13
|
"path": ".claude/agents",
|
|
14
14
|
"description": "AI agent definitions (flat .md files with prefixes)",
|
|
15
|
-
"files":
|
|
15
|
+
"files": 49
|
|
16
16
|
},
|
|
17
17
|
{
|
|
18
18
|
"name": "skills",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
"name": "guides",
|
|
25
25
|
"path": "guides",
|
|
26
26
|
"description": "Reference documentation",
|
|
27
|
-
"files":
|
|
27
|
+
"files": 43
|
|
28
28
|
},
|
|
29
29
|
{
|
|
30
30
|
"name": "hooks",
|