super-opencode 1.1.2 → 1.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.
Files changed (48) hide show
  1. package/.opencode/agents/architect.md +54 -31
  2. package/.opencode/agents/backend.md +61 -34
  3. package/.opencode/agents/data-agent.md +422 -0
  4. package/.opencode/agents/devops-agent.md +331 -0
  5. package/.opencode/agents/frontend.md +63 -36
  6. package/.opencode/agents/mobile-agent.md +636 -0
  7. package/.opencode/agents/optimizer.md +25 -18
  8. package/.opencode/agents/pm-agent.md +114 -50
  9. package/.opencode/agents/quality.md +36 -29
  10. package/.opencode/agents/researcher.md +30 -21
  11. package/.opencode/agents/reviewer.md +39 -32
  12. package/.opencode/agents/security.md +42 -34
  13. package/.opencode/agents/writer.md +42 -31
  14. package/.opencode/commands/soc-analyze.md +55 -31
  15. package/.opencode/commands/soc-brainstorm.md +48 -26
  16. package/.opencode/commands/soc-cleanup.md +47 -25
  17. package/.opencode/commands/soc-deploy.md +271 -0
  18. package/.opencode/commands/soc-design.md +51 -26
  19. package/.opencode/commands/soc-explain.md +46 -23
  20. package/.opencode/commands/soc-git.md +47 -25
  21. package/.opencode/commands/soc-help.md +35 -14
  22. package/.opencode/commands/soc-implement.md +59 -29
  23. package/.opencode/commands/soc-improve.md +42 -20
  24. package/.opencode/commands/soc-onboard.md +329 -0
  25. package/.opencode/commands/soc-plan.md +215 -0
  26. package/.opencode/commands/soc-pm.md +40 -18
  27. package/.opencode/commands/soc-research.md +43 -20
  28. package/.opencode/commands/soc-review.md +39 -18
  29. package/.opencode/commands/soc-test.md +43 -21
  30. package/.opencode/commands/soc-validate.md +221 -0
  31. package/.opencode/commands/soc-workflow.md +38 -17
  32. package/.opencode/skills/confidence-check/SKILL.md +26 -19
  33. package/.opencode/skills/debug-protocol/SKILL.md +27 -17
  34. package/.opencode/skills/decision-log/SKILL.md +236 -0
  35. package/.opencode/skills/doc-sync/SKILL.md +345 -0
  36. package/.opencode/skills/package-manager/SKILL.md +502 -0
  37. package/.opencode/skills/package-manager/scripts/README.md +106 -0
  38. package/.opencode/skills/package-manager/scripts/detect-package-manager.sh +796 -0
  39. package/.opencode/skills/reflexion/SKILL.md +18 -11
  40. package/.opencode/skills/security-audit/SKILL.md +19 -14
  41. package/.opencode/skills/self-check/SKILL.md +30 -14
  42. package/.opencode/skills/simplification/SKILL.md +19 -5
  43. package/.opencode/skills/tech-debt/SKILL.md +245 -0
  44. package/LICENSE +1 -1
  45. package/README.md +126 -9
  46. package/dist/cli.js +143 -41
  47. package/package.json +27 -12
  48. package/.opencode/settings.json +0 -3
@@ -6,12 +6,14 @@ description: Post-action analysis to generate heuristics, update project memory,
6
6
  # Reflexion Skill
7
7
 
8
8
  ## Purpose
9
+
9
10
  To transform **Failures** into **Heuristics**.
10
11
  Reflexion is the cognitive step that occurs **after** a failed attempt and **before** the next attempt. It breaks the "Insanity Loop" (doing the same thing twice expecting different results).
11
12
 
12
13
  **ROI Metric**: Prevents 5-10 wasted attempts in a loop by forcing a strategy shift after the first failure.
13
14
 
14
15
  ## When to Use
16
+
15
17
  - **Automatic Trigger**: After a tool error (e.g., `bash` exit code != 0).
16
18
  - **Automatic Trigger**: After a test failure during `execution` mode.
17
19
  - **Manual Trigger**: When the user rejects an artifact ("This isn't what I asked for").
@@ -20,24 +22,28 @@ Reflexion is the cognitive step that occurs **after** a failed attempt and **bef
20
22
  ## The Reflexion Protocol (The Loop)
21
23
 
22
24
  ### 1. The Halt (Stop)
25
+
23
26
  **Rule**: *Never retry immediately.*
24
27
  If an error occurs, you must pause. Do not simply re-run the command hoping for a different outcome.
25
28
 
26
29
  ### 2. The Trace (Diagnosis)
30
+
27
31
  **Action**: Analyze the mismatch between *Expected Output* and *Actual Output*.
28
- * *Was it a Syntax Error?* (Context failure).
29
- * *Was it a Logic Error?* (Reasoning failure).
30
- * *Was it a Hallucination?* (Knowledge failure).
32
+ - *Was it a Syntax Error?* (Context failure).
33
+ - *Was it a Logic Error?* (Reasoning failure).
34
+ - *Was it a Hallucination?* (Knowledge failure).
31
35
 
32
36
  ### 3. The Heuristic (Correction)
37
+
33
38
  **Action**: Create a new rule for yourself.
34
- * *Old Thought:* "I will use `rm -rf` to clean up."
35
- * *New Heuristic:* "I must check if the directory exists before attempting delete."
39
+ - *Old Thought:* "I will use `rm -rf` to clean up."
40
+ - *New Heuristic:* "I must check if the directory exists before attempting delete."
36
41
 
37
42
  ### 4. The Store (Memory)
43
+
38
44
  **Action**: Save this lesson.
39
- * *Short-term:* Apply to current context window.
40
- * *Long-term:* Write to `.opencode/memory/patterns.md`.
45
+ - *Short-term:* Apply to current context window.
46
+ - *Long-term:* Write to `.opencode/memory/patterns.md`.
41
47
 
42
48
  ## Execution Template
43
49
 
@@ -77,6 +83,7 @@ Maintain a dedicated memory structure to allow the `researcher` and `pm-agent` t
77
83
  ```
78
84
 
79
85
  ### Example: `.opencode/memory/anti_patterns.md`
86
+
80
87
  ```markdown
81
88
  ## ⛔ Anti-Patterns
82
89
 
@@ -93,10 +100,10 @@ Maintain a dedicated memory structure to allow the `researcher` and `pm-agent` t
93
100
 
94
101
  ## Integration with Agents
95
102
 
96
- - **`execution` agent**: Must trigger `reflexion` after 2 failed build attempts.
97
- - *Logic:* "Attempt 1 Failed -> Retry -> Attempt 2 Failed -> **STOP & REFLECT** -> Attempt 3".
98
- - **`pm-agent`**: Reads `.opencode/memory/patterns.md` at the start of a new task to load context.
99
- - **`writer`**: Uses successful reflexions to update the project's `README.md` or `CONTRIBUTING.md`.
103
+ - **`execution` agent**: Must trigger `reflexion` after 2 failed build attempts.
104
+ - *Logic:* "Attempt 1 Failed -> Retry -> Attempt 2 Failed -> **STOP & REFLECT** -> Attempt 3".
105
+ - **`pm-agent`**: Reads `.opencode/memory/patterns.md` at the start of a new task to load context.
106
+ - **`writer`**: Uses successful reflexions to update the project's `README.md` or `CONTRIBUTING.md`.
100
107
 
101
108
  ## Reflexion vs. Debugging
102
109
 
@@ -6,20 +6,23 @@ description: Static Analysis and Threat Modeling skill to detect OWASP Top 10 vu
6
6
  # Security Audit Skill
7
7
 
8
8
  ## Purpose
9
+
9
10
  To act as an automated **SAST (Static Application Security Testing)** scanner.
10
11
  **Goal**: Identify vulnerabilities in the *implementation* phase, before the code reaches the `review` phase.
11
12
 
12
13
  **ROI Metric**: Detecting a hardcoded secret here takes 5 seconds. Rotating a compromised key in production takes 5 hours.
13
14
 
14
15
  ## When to Use
15
- - **Trigger**: When `backend` implements an endpoint involving `users`, `auth`, or `payments`.
16
- - **Trigger**: When `frontend` uses `dangerouslySetInnerHTML` or similar raw HTML rendering.
17
- - **Trigger**: When `pm-agent` flags a task as "High Risk."
18
- - **Agent**: Primary skill for the `security` agent; secondary skill for `backend`/`review` modes.
16
+
17
+ - **Trigger**: When `backend` implements an endpoint involving `users`, `auth`, or `payments`.
18
+ - **Trigger**: When `frontend` uses `dangerouslySetInnerHTML` or similar raw HTML rendering.
19
+ - **Trigger**: When `pm-agent` flags a task as "High Risk."
20
+ - **Agent**: Primary skill for the `security` agent; secondary skill for `backend`/`review` modes.
19
21
 
20
22
  ## The Audit Protocol (The Scanner)
21
23
 
22
24
  ### 1. Pattern Scanning (The Grep Check)
25
+
23
26
  *Scan the code for these specific "smells":*
24
27
 
25
28
  | Risk Category | Keywords/Patterns to Flag |
@@ -31,16 +34,18 @@ To act as an automated **SAST (Static Application Security Testing)** scanner.
31
34
  | **Debug Leftovers** | `console.log(userObj)`, `debugger`, `0.0.0.0` (binding to all interfaces) |
32
35
 
33
36
  ### 2. Logic Analysis (STRIDE)
37
+
34
38
  *Ask these questions about the flow:*
35
- * **Spoofing**: Does this verify *who* the user is? (Check: Auth Middleware presence).
36
- * **Tampering**: Can I modify the payload? (Check: Zod/Joi validation `strip()` on unknown keys).
37
- * **Information Disclosure**: Does the error return the stack trace? (Check: `try/catch` blocks).
38
- * **Elevation of Privilege**: Does it check `user.id === resource.ownerId`? (Check: Authorization logic).
39
+ - **Spoofing**: Does this verify *who* the user is? (Check: Auth Middleware presence).
40
+ - **Tampering**: Can I modify the payload? (Check: Zod/Joi validation `strip()` on unknown keys).
41
+ - **Information Disclosure**: Does the error return the stack trace? (Check: `try/catch` blocks).
42
+ - **Elevation of Privilege**: Does it check `user.id === resource.ownerId`? (Check: Authorization logic).
39
43
 
40
44
  ### 3. Dependency Check (Supply Chain)
41
- * If `package.json` was modified:
42
- * Are versions pinned? (Good: `1.2.3`, Bad: `^1.2.3`).
43
- * Are there known CVEs? (Trigger `tavily` search).
45
+
46
+ * If `package.json` was modified:
47
+ - Are versions pinned? (Good: `1.2.3`, Bad: `^1.2.3`).
48
+ - Are there known CVEs? (Trigger `tavily` search).
44
49
 
45
50
  ## Execution Template
46
51
 
@@ -85,6 +90,6 @@ To act as an automated **SAST (Static Application Security Testing)** scanner.
85
90
 
86
91
  ## Integration with Agents
87
92
 
88
- - **`security` agent**: Uses this skill as its primary method of interaction.
89
- - **`backend` agent**: Must invoke `security-audit` before marking an API task as "Complete."
90
- - **`review` mode**: Uses the *Findings Table* as the basis for "Critical" comments.
93
+ - **`security` agent**: Uses this skill as its primary method of interaction.
94
+ - **`backend` agent**: Must invoke `security-audit` before marking an API task as "Complete."
95
+ - **`review` mode**: Uses the *Findings Table* as the basis for "Critical" comments.
@@ -6,37 +6,47 @@ description: Post-implementation validation to enforce the Definition of Done (D
6
6
  # Self-Check Skill
7
7
 
8
8
  ## Purpose
9
+
9
10
  To validate work **after** implementation but **before** handoff.
10
11
  This is the "Check" in PDCA. It prevents the "It works on my machine" (or "It works in my context window") syndrome.
11
12
 
12
13
  **ROI Metric**: Catching a syntax error here costs 50 tokens. Catching it in a PR review costs 5,000 tokens + human time.
13
14
 
14
15
  ## When to Use
15
- - **Trigger**: Immediately after `execution` mode finishes writing code.
16
- - **Trigger**: Before the `backend` agent hands off to `frontend`.
17
- - **Trigger**: Before any `git commit`.
16
+
17
+ - **Trigger**: Immediately after `execution` mode finishes writing code.
18
+ - **Trigger**: Before the `backend` agent hands off to `frontend`.
19
+ - **Trigger**: Before any `git commit`.
18
20
 
19
21
  ## The "Proof of Work" Protocol
20
22
 
21
23
  ### 1. The Build Check (Syntax)
24
+
22
25
  **Rule**: *Code that doesn't build doesn't exist.*
23
- - Did you run the build/transpile command? (`npm run build`, `go build`, etc.)
24
- - **Evidence**: Paste the exit code and the last 3 lines of output.
26
+
27
+ - Did you run the build/transpile command? (`npm run build`, `go build`, etc.)
28
+ - **Evidence**: Paste the exit code and the last 3 lines of output.
25
29
 
26
30
  ### 2. The Logic Check (Behavior)
31
+
27
32
  **Rule**: *Claims require proof.*
28
- - **Forbidden Phrase**: "I ran the tests and they passed." (This is often a hallucination).
29
- - **Required Action**: Run the test command via `run_command` and capture the actual output.
30
- - **Evidence**: Paste the `Total: X Passed, 0 Failed` line.
33
+
34
+ - **Forbidden Phrase**: "I ran the tests and they passed." (This is often a hallucination).
35
+ - **Required Action**: Run the test command via `run_command` and capture the actual output.
36
+ - **Evidence**: Paste the `Total: X Passed, 0 Failed` line.
31
37
 
32
38
  ### 3. The Contract Check (Requirements)
39
+
33
40
  **Rule**: *Did you solve the user's problem?*
34
- - Map every constraint from the original prompt to a specific line of code or test case.
41
+
42
+ - Map every constraint from the original prompt to a specific line of code or test case.
35
43
 
36
44
  ### 4. The Hygiene Check (Cleanup)
45
+
37
46
  **Rule**: *Leave no trace.*
38
- - Scan for: `console.log("here")`, `debugger`, commented out code blocks, or `TODO` comments added by you.
39
- - **Action**: Remove them.
47
+
48
+ - Scan for: `console.log("here")`, `debugger`, commented out code blocks, or `TODO` comments added by you.
49
+ - **Action**: Remove them.
40
50
 
41
51
  ## Execution Template
42
52
 
@@ -53,24 +63,30 @@ This is the "Check" in PDCA. It prevents the "It works on my machine" (or "It wo
53
63
  > tsc
54
64
  ✨ Done in 2.45s.
55
65
  ```
66
+
56
67
  - **Status**: [ PASS / FAIL ]
57
68
 
58
69
  ### 2. Test Verification
70
+
59
71
  - **Command**: `npm test -- user.service.test.ts`
60
72
  - **Output**:
73
+
61
74
  ```text
62
75
  PASS src/services/user.service.test.ts
63
76
  Tests: 3 passed, 3 total
64
77
  ```
78
+
65
79
  - **Status**: [ PASS / FAIL ] -> *If FAIL, trigger `reflexion` skill.*
66
80
 
67
81
  ### 3. Requirements Mapping
82
+
68
83
  | Requirement | Implemented? | Evidence (File/Line) |
69
84
  | :--- | :--- | :--- |
70
85
  | "Users must have a role" | ✅ | `UserSchema.ts:12` (Zod enum) |
71
86
  | "Passwords must be hashed" | ✅ | `AuthService.ts:45` (bcrypt call) |
72
87
 
73
88
  ### 4. Code Hygiene
89
+
74
90
  - [ ] Removed debug `console.log`s?
75
91
  - [ ] Removed temporary comments?
76
92
  - [ ] Ran Linter? (`npm run lint`)
@@ -90,6 +106,6 @@ If you see these patterns in your own reasoning, **STOP**:
90
106
 
91
107
  ## Integration with Agents
92
108
 
93
- - **`execution` mode**: Must run `self-check` before declaring `Status: COMPLETE`.
94
- - **`pm-agent`**: Rejects any task update that does not include a `self-check` artifact.
95
- - **`reflexion` skill**: If `self-check` results in **FAIL**, the agent must immediately enter `reflexion` mode to analyze the root cause before retrying.
109
+ - **`execution` mode**: Must run `self-check` before declaring `Status: COMPLETE`.
110
+ - **`pm-agent`**: Rejects any task update that does not include a `self-check` artifact.
111
+ - **`reflexion` skill**: If `self-check` results in **FAIL**, the agent must immediately enter `reflexion` mode to analyze the root cause before retrying.
@@ -6,47 +6,57 @@ description: Complexity reduction and architectural streamlining for Frontend, B
6
6
  # Simplification Skill (Occam's Razor)
7
7
 
8
8
  ## Purpose
9
+
9
10
  "Simplicity is the ultimate sophistication." This skill provides a rigorous protocol for identifying and eliminating over-engineering, code bloat, and technical debt across the entire stack.
10
11
 
11
12
  ## Overview
13
+
12
14
  The Simplification Skill is a cross-functional protocol used to flatten logic, reduce state, and ensure every line of code justifies its existence. It leverages specialized agents and MCP tools to validate architectural simplicity and performance.
13
15
 
14
16
  ## Prerequisites
17
+
15
18
  - **Agents**: [Backend](file:///.opencode/agents/backend.md), [Frontend](file:///.opencode/agents/frontend.md), [Quality](file:///.opencode/agents/quality.md).
16
- - **MCP Tools**:
17
- - `context7`: To research lightweight alternatives and library standards.
18
- - `sequential-thinking`: To audit complex logic flows for potential flattening.
19
- - `sqlite`: To verify if database schemas or queries can be compressed.
20
- - `playwright`/`chrome-devtools`: To identify UI "jank" or DOM complexity.
19
+ - **MCP Tools**:
20
+ - `context7`: To research lightweight alternatives and library standards.
21
+ - `sequential-thinking`: To audit complex logic flows for potential flattening.
22
+ - `sqlite`: To verify if database schemas or queries can be compressed.
23
+ - `playwright`/`chrome-devtools`: To identify UI "jank" or DOM complexity.
21
24
 
22
25
  ## Agent-Specific Simplification Protocols
23
26
 
24
27
  ### [Senior Backend Engineer](file:///.opencode/agents/backend.md)
28
+
25
29
  - **State Reduction**: Derive values instead of storing them. If `is_active` can be derived from `status === 'active'`, delete the redundant field.
26
30
  - **Query Optimization**: Use `sqlite` to check for N+1 issues. Replace nested loops with single optimized queries or batching.
27
31
  - **Error Flattening**: Centralize error handling middleware. Remove repetitive `try/catch` blocks from business logic to expose the "Happy Path".
28
32
 
29
33
  ### [Senior Frontend Engineer](file:///.opencode/agents/frontend.md)
34
+
30
35
  - **DOM Streamlining**: Replace "Div Soup" with semantic HTML elements.
31
36
  - **Hook Optimization**: Audit `useEffect` usage. If it's used to sync state, replace it with derived constants or `useMemo`.
32
37
  - **Styling Discipline**: Replace custom inline styles with standard Tailwind utility classes or `cva` variants.
33
38
 
34
39
  ### [QA Automation Engineer](file:///.opencode/agents/quality.md)
40
+
35
41
  - **Test Pruning**: Remove redundant unit tests if the logic is covered by a high-confidence integration test.
36
42
  - **Selector Simplification**: Replace fragile XPaths or class-based selectors with accessible `getByRole` or `getByLabel` locators.
37
43
 
38
44
  ## The Procedural Workflow
39
45
 
40
46
  ### 1. The Deletion Test
47
+
41
48
  - **Action**: Use `grep_search` to find references to the target code. If references < 1, **DELETE**.
42
49
  - **Rule**: Dead code is the best code.
43
50
 
44
51
  ### 2. The Library Leverage (via `context7`)
52
+
45
53
  - **Action**: Use `context7` to check if a complex custom utility (e.g., date formatting, deep cloning) can be replaced by a native function or a lightweight standard library (Lodash/Zustand).
46
54
 
47
55
  ### 3. Flat Logic Audit (via `sequential-thinking`)
56
+
48
57
  - **Action**: Step through the logic. If nesting > 3 levels or cyclomatic complexity is high, apply guard clauses.
49
58
  - **Target Pattern**:
59
+
50
60
  ```diff
51
61
  - if (user) {
52
62
  - if (user.active) {
@@ -58,6 +68,7 @@ The Simplification Skill is a cross-functional protocol used to flatten logic, r
58
68
  ```
59
69
 
60
70
  ## Complexity Metrics to Watch
71
+
61
72
  - **Nesting Level**: Maximum 3 levels of indentation.
62
73
  - **Function Size**: Maximum 30 lines.
63
74
  - **Cognitive Weight**: If a function requires `sequential-thinking` just to "read" it, it's too complex.
@@ -81,12 +92,15 @@ The Simplification Skill is a cross-functional protocol used to flatten logic, r
81
92
  ```
82
93
 
83
94
  **After**:
95
+
84
96
  ```javascript
85
97
  // Streamlined, readable, and efficient code
86
98
  ```
87
99
 
88
100
  ### 3. Impact Assessment
101
+
89
102
  - Lines Removed: [Count]
90
103
  - Performance Gain: [e.g., Reduced O(N²) to O(N)]
91
104
  - Maintenance Status: Optimized
105
+
92
106
  ```
@@ -0,0 +1,245 @@
1
+ ---
2
+ name: tech-debt
3
+ description: Technical debt identification, prioritization, and strategic repayment planning.
4
+ ---
5
+
6
+ # Tech Debt Skill
7
+
8
+ ## Purpose
9
+
10
+ To transform **silent code rot** into **managed, prioritized backlog items**. This skill provides a systematic approach to identifying, quantifying, and scheduling technical debt repayment—preventing the "big bang" rewrite and enabling sustainable development velocity.
11
+
12
+ **ROI Metric**: Addressing debt early costs 1x. Addressing it late costs 10x. Ignoring it costs 100x (failed projects).
13
+
14
+ ## When to Use
15
+
16
+ - **Trigger**: When velocity is slowing down (features taking longer).
17
+ - **Trigger**: When `reflexion` identifies recurring issues.
18
+ - **Trigger**: Before major feature work ("Clean the campsite first").
19
+ - **Trigger**: When code complexity metrics exceed thresholds.
20
+ - **Trigger**: When `pm-agent` schedules a "debt sprint."
21
+
22
+ ## The Debt Management Protocol (The 4-Step Process)
23
+
24
+ ### 1. Identification (Where Is The Debt?)
25
+
26
+ **Scan for these debt signals:**
27
+
28
+ | Signal | Detection Method | Example |
29
+ |:-------|:-----------------|:--------|
30
+ | **Code Smells** | Static analysis, complexity metrics | Functions >50 lines, nested conditionals >3 levels |
31
+ | **Outdated Dependencies** | `npm outdated`, `cargo outdated` | React 16 when 18 is available |
32
+ | **Missing Tests** | Coverage reports | Critical path has <50% coverage |
33
+ | **Documentation Drift** | Doc vs code comparison | API docs don't match implementation |
34
+ | **Workarounds** | Code comments (`// HACK`, `// FIXME`) | Temporary fixes that became permanent |
35
+ | **Performance Issues** | Profiling, metrics | Page load >3s, API latency >500ms |
36
+ | **Security Vulnerabilities** | `npm audit`, SAST scans | Known CVEs in dependencies |
37
+
38
+ ### 2. Quantification (How Bad Is It?)
39
+
40
+ Score each debt item across three dimensions:
41
+
42
+ **Impact (1-10)**: How much does this hurt?
43
+ - Development velocity
44
+ - System reliability
45
+ - Security posture
46
+ - User experience
47
+
48
+ **Effort (1-10)**: How hard to fix?
49
+ - Lines of code to change
50
+ - Files affected
51
+ - Dependencies to update
52
+ - Tests to write
53
+ - Risk of breaking changes
54
+
55
+ **Interest Rate (1-10)**: How fast is it growing?
56
+ - How often does this code change?
57
+ - How many new features touch this area?
58
+ - How many workarounds are being added?
59
+
60
+ **Debt Score = Impact × Interest Rate / Effort**
61
+
62
+ Higher score = Pay this debt first.
63
+
64
+ ### 3. Categorization (What Type Of Debt?)
65
+
66
+ | Category | Description | Example | Typical Action |
67
+ |:---------|:------------|:--------|:-------------|
68
+ | **Design Debt** | Architectural shortcuts | God class, tight coupling | Refactor with ADR |
69
+ | **Code Debt** | Implementation shortcuts | Copy-pasted code, long methods | Refactor incrementally |
70
+ | **Test Debt** | Missing or poor tests | No integration tests | Write tests before changes |
71
+ | **Documentation Debt** | Outdated or missing docs | API changes not documented | Update docs as you go |
72
+ | **Dependency Debt** | Outdated libraries | React 16 in 2026 | Scheduled upgrade |
73
+ | **Infrastructure Debt** | Ops shortcuts | Manual deploys | Automate via IaC |
74
+ | **Skill Debt** | Team knowledge gaps | No one knows GraphQL | Training + pairing |
75
+
76
+ ### 4. Scheduling (When Do We Pay?)
77
+
78
+ **Strategies:**
79
+
80
+ **A. Debt Sprints (20% Rule)**
81
+ - Reserve 20% of every sprint for debt repayment.
82
+ - Pay highest-scored debt items first.
83
+ - Track debt burndown like feature burndown.
84
+
85
+ **B. Boy Scout Rule**
86
+ - "Leave the code better than you found it."
87
+ - Small improvements with every feature PR.
88
+ - Limit: 10-20% of PR scope should be cleanup.
89
+
90
+ **C. Before New Features**
91
+ - Clean debt in the area you're about to modify.
92
+ - Prevents building on shaky foundations.
93
+
94
+ **D. Scheduled Maintenance**
95
+ - Quarterly dependency updates.
96
+ - Bi-annual architecture reviews.
97
+ - Annual security audits.
98
+
99
+ ## Debt Item Template
100
+
101
+ ```markdown
102
+ # Tech Debt Item: [TITLE]
103
+
104
+ ## Summary
105
+ **ID**: DEBT-XXX
106
+ **Category**: [Design/Code/Test/Doc/Dependency/Infra/Skill]
107
+ **Filed Date**: YYYY-MM-DD
108
+ **Status**: Identified | Scheduled | In Progress | Paid
109
+
110
+ ## Problem Statement
111
+ [What is the debt? What are the symptoms?]
112
+
113
+ [Example: The UserService class has grown to 2000 lines and handles authentication, profile management, and preferences. Changes require touching 15+ methods.]
114
+
115
+ ## Impact Assessment
116
+
117
+ | Dimension | Score (1-10) | Justification |
118
+ |:----------|:------------:|:--------------|
119
+ | **Impact** | 8 | Every user feature touches this class. Changes are slow and error-prone. |
120
+ | **Effort** | 6 | Requires splitting into 3-4 services. Estimated 3 days. |
121
+ | **Interest Rate** | 9 | We add 2-3 new user features per sprint. Debt grows fast. |
122
+
123
+ **Debt Score**: (8 × 9) / 6 = **12.0** [Pay Immediately: >10]
124
+
125
+ ## Symptoms
126
+ - [ ] Feature X took 5 days instead of 2
127
+ - [ ] Bug Y introduced because of tight coupling
128
+ - [ ] Developer onboarding takes 3 days to understand UserService
129
+ - [ ] Tests are flaky due to too many responsibilities
130
+
131
+ ## Proposed Solution
132
+ [What should we do to pay this debt?]
133
+
134
+ [Example: Split UserService into AuthService, ProfileService, and PreferenceService. Each <300 lines.]
135
+
136
+ ### Steps
137
+ 1. [ ] Step 1: Create ProfileService, move profile methods
138
+ 2. [ ] Step 2: Update tests for ProfileService
139
+ 3. [ ] Step 3: Create PreferenceService, move preference methods
140
+ 4. [ ] Step 4: Update tests for PreferenceService
141
+ 5. [ ] Step 5: Refactor UserService to AuthService only
142
+ 6. [ ] Step 6: Update all imports and calls
143
+ 7. [ ] Step 7: Verify all tests pass
144
+
145
+ ## Risks & Mitigations
146
+ - **Risk**: Breaking changes to API → Mitigation: Maintain backward-compatible wrapper during transition
147
+ - **Risk**: Tests need major rewrite → Mitigation: Write new service tests before migration
148
+
149
+ ## Payment Schedule
150
+ - **Strategy**: Before New Feature
151
+ - **Scheduled Sprint**: Sprint 12 (when we build User Preferences v2)
152
+ - **Owner**: @backend-team
153
+ - **Estimated Effort**: 3 days
154
+
155
+ ## Notes
156
+ - **Related PRs**: #123, #456
157
+ - **Related ADRs**: ADR-002 (Service Boundaries)
158
+ - **Outcome (when paid)**: [To be filled]
159
+ ```
160
+
161
+ ## Execution Template
162
+
163
+ *Use this when running a debt audit.*
164
+
165
+ ```markdown
166
+ ## 🔍 Tech Debt Audit: [Scope]
167
+
168
+ ### 1. Scan Results
169
+
170
+ | ID | Category | Location | Impact | Effort | Interest | Score | Priority |
171
+ |:---|:---------|:---------|:------:|:------:|:--------:|:-----:|:--------:|
172
+ | D-001 | Design | UserService.ts | 8 | 6 | 9 | 12.0 | HIGH |
173
+ | D-002 | Dependency | React 16.x | 6 | 4 | 7 | 10.5 | HIGH |
174
+ | D-003 | Test | auth/ | 7 | 3 | 6 | 14.0 | HIGH |
175
+ | D-004 | Code | utils/helpers.js | 4 | 2 | 3 | 6.0 | MEDIUM |
176
+
177
+ ### 2. High Priority Items (Score >10)
178
+
179
+ #### D-003: Missing Auth Tests
180
+ **Problem**: Authentication flows have 23% test coverage.
181
+ **Impact**: Every auth change risks regression.
182
+ **Solution**: Write integration tests for all auth flows.
183
+ **Effort**: 2 days
184
+ **Schedule**: Next sprint (Sprint 11)
185
+
186
+ ### 3. Payment Plan
187
+
188
+ **This Sprint (Sprint 10)**
189
+ - [ ] D-004: Refactor utils/helpers.js (1 day)
190
+ - Feature work: 80%
191
+ - Debt work: 20%
192
+
193
+ **Next Sprint (Sprint 11)**
194
+ - [ ] D-003: Auth test coverage (2 days)
195
+ - [ ] D-002: React upgrade planning (1 day)
196
+ - Feature work: 70%
197
+ - Debt work: 30%
198
+
199
+ **Following Sprint (Sprint 12)**
200
+ - [ ] D-001: Split UserService (3 days)
201
+ - Feature work: 60%
202
+ - Debt work: 40%
203
+
204
+ ### 4. Debt Metrics
205
+ - **Total Items**: 4
206
+ - **High Priority**: 3
207
+ - **Estimated Total Effort**: 12 days
208
+ - **Debt Burndown Target**: 0 high-priority items by end of Q2
209
+ ```
210
+
211
+ ## Debt Register
212
+
213
+ Maintain a central debt register:
214
+
215
+ ```markdown
216
+ # Technical Debt Register
217
+
218
+ ## Active Debt
219
+ | ID | Title | Category | Score | Status | Owner | Target Sprint |
220
+ |:---|:------|:---------|:-----:|:-------|:------|:-------------:|
221
+ | D-001 | UserService too large | Design | 12.0 | Scheduled | Backend | 12 |
222
+ | D-002 | React 16 outdated | Dependency | 10.5 | Scheduled | Frontend | 11 |
223
+ | D-003 | Auth tests missing | Test | 14.0 | In Progress | Quality | 11 |
224
+
225
+ ## Recently Paid
226
+ | ID | Title | Category | Paid Date | Effort | Outcome |
227
+ |:---|:------|:---------|:----------|:-------|:--------|
228
+ | D-000 | Legacy API wrapper | Code | 2026-01-15 | 2 days | API response time -30% |
229
+ ```
230
+
231
+ ## Integration with Agents
232
+
233
+ - **`architect`**: Identifies design debt, creates ADRs for major refactors.
234
+ - **`backend` / `frontend`**: Identifies code debt during implementation.
235
+ - **`quality`**: Identifies test debt from coverage reports.
236
+ - **`pm-agent`**: Schedules debt sprints, tracks debt burndown.
237
+ - **`reflexion`**: Surfaces recurring issues that become debt items.
238
+
239
+ ## Anti-Patterns (Avoid)
240
+
241
+ - ❌ **"We'll fix it later"** without scheduling → Becomes permanent
242
+ - ❌ **Big Bang Rewrite** → High risk, hard to validate
243
+ - ❌ **Perfect is Enemy of Good** → Don't gold-plate while debt accumulates
244
+ - ❌ **Debt Amnesty** → Don't ignore debt because "it's always been there"
245
+ - ❌ **Paying Low-Score Debt First** → Focus on high-impact, high-interest debt
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 Super-OpenCode
3
+ Copyright (c) 2026 SIO TOU LAI
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal