@kkelly-offical/kkcode 0.1.6 → 0.2.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.
Files changed (163) hide show
  1. package/LICENSE +674 -674
  2. package/README.md +452 -387
  3. package/package.json +50 -46
  4. package/src/agent/agent.mjs +19 -2
  5. package/src/agent/custom-agent-loader.mjs +6 -3
  6. package/src/agent/generator.mjs +2 -2
  7. package/src/agent/prompt/assistant.txt +12 -0
  8. package/src/agent/prompt/bug-hunter.txt +90 -0
  9. package/src/agent/prompt/frontend-designer.txt +58 -58
  10. package/src/agent/prompt/guide.txt +1 -1
  11. package/src/agent/prompt/longagent-blueprint-agent.txt +83 -83
  12. package/src/agent/prompt/longagent-coding-agent.txt +37 -37
  13. package/src/agent/prompt/longagent-debugging-agent.txt +46 -46
  14. package/src/agent/prompt/longagent-preview-agent.txt +63 -63
  15. package/src/command/custom-commands.mjs +2 -2
  16. package/src/commands/agent.mjs +1 -1
  17. package/src/commands/background.mjs +145 -4
  18. package/src/commands/chat.mjs +117 -76
  19. package/src/commands/config.mjs +148 -1
  20. package/src/commands/doctor.mjs +30 -6
  21. package/src/commands/init.mjs +32 -6
  22. package/src/commands/longagent.mjs +117 -0
  23. package/src/commands/mcp.mjs +275 -43
  24. package/src/commands/permission.mjs +1 -1
  25. package/src/commands/session.mjs +195 -140
  26. package/src/commands/skill.mjs +63 -0
  27. package/src/commands/theme.mjs +1 -1
  28. package/src/config/defaults.mjs +280 -260
  29. package/src/config/import-config.mjs +1 -1
  30. package/src/config/load-config.mjs +61 -4
  31. package/src/config/schema.mjs +591 -574
  32. package/src/context.mjs +4 -1
  33. package/src/core/constants.mjs +97 -91
  34. package/src/core/types.mjs +1 -1
  35. package/src/github/api.mjs +78 -78
  36. package/src/github/auth.mjs +294 -286
  37. package/src/github/flow.mjs +298 -298
  38. package/src/github/workspace.mjs +225 -212
  39. package/src/index.mjs +84 -82
  40. package/src/knowledge/frontend-aesthetics.txt +38 -38
  41. package/src/mcp/client-http.mjs +139 -141
  42. package/src/mcp/client-sse.mjs +297 -288
  43. package/src/mcp/client-stdio.mjs +534 -533
  44. package/src/mcp/constants.mjs +2 -2
  45. package/src/mcp/registry.mjs +498 -479
  46. package/src/mcp/stdio-framing.mjs +135 -133
  47. package/src/mcp/tool-result.mjs +24 -24
  48. package/src/observability/edit-diagnostics.mjs +449 -0
  49. package/src/observability/index.mjs +42 -42
  50. package/src/observability/metrics.mjs +165 -137
  51. package/src/observability/tracer.mjs +137 -137
  52. package/src/onboarding.mjs +209 -0
  53. package/src/orchestration/background-manager.mjs +567 -372
  54. package/src/orchestration/background-worker.mjs +419 -305
  55. package/src/orchestration/interruption-reason.mjs +21 -0
  56. package/src/orchestration/longagent-manager.mjs +197 -171
  57. package/src/orchestration/stage-scheduler.mjs +733 -728
  58. package/src/orchestration/subagent-router.mjs +7 -1
  59. package/src/orchestration/task-scheduler.mjs +219 -7
  60. package/src/permission/engine.mjs +1 -1
  61. package/src/permission/exec-policy.mjs +370 -370
  62. package/src/permission/file-edit-policy.mjs +108 -0
  63. package/src/permission/prompt.mjs +1 -1
  64. package/src/permission/rules.mjs +116 -7
  65. package/src/plugin/builtin-hooks/post-edit-format.mjs +2 -1
  66. package/src/plugin/builtin-hooks/post-edit-typecheck.mjs +104 -40
  67. package/src/plugin/hook-bus.mjs +19 -5
  68. package/src/plugin/manifest-loader.mjs +222 -0
  69. package/src/provider/anthropic.mjs +396 -390
  70. package/src/provider/ollama.mjs +7 -1
  71. package/src/provider/openai.mjs +382 -340
  72. package/src/provider/retry-policy.mjs +74 -68
  73. package/src/provider/router.mjs +242 -241
  74. package/src/provider/sse.mjs +104 -104
  75. package/src/provider/wizard.mjs +556 -0
  76. package/src/repl/capability-facade.mjs +30 -0
  77. package/src/repl/command-surface.mjs +23 -0
  78. package/src/repl/controller-entry.mjs +40 -0
  79. package/src/repl/core-shell.mjs +208 -0
  80. package/src/repl/dialog-router.mjs +87 -0
  81. package/src/repl/input-engine.mjs +76 -0
  82. package/src/repl/keymap.mjs +7 -0
  83. package/src/repl/operator-surface.mjs +15 -0
  84. package/src/repl/permission-flow.mjs +49 -0
  85. package/src/repl/runtime-facade.mjs +36 -0
  86. package/src/repl/slash-router.mjs +62 -0
  87. package/src/repl/state-store.mjs +29 -0
  88. package/src/repl/turn-controller.mjs +58 -0
  89. package/src/repl/verification.mjs +23 -0
  90. package/src/repl.mjs +3368 -2929
  91. package/src/rules/load-rules.mjs +3 -3
  92. package/src/runtime.mjs +1 -1
  93. package/src/session/agent-transaction.mjs +86 -0
  94. package/src/session/checkpoint.mjs +302 -302
  95. package/src/session/compaction.mjs +36 -14
  96. package/src/session/engine.mjs +417 -227
  97. package/src/session/longagent-4stage.mjs +467 -460
  98. package/src/session/longagent-hybrid.mjs +1344 -1081
  99. package/src/session/longagent-plan.mjs +376 -365
  100. package/src/session/longagent-project-memory.mjs +53 -53
  101. package/src/session/longagent-scaffold.mjs +291 -291
  102. package/src/session/longagent-task-bus.mjs +138 -54
  103. package/src/session/longagent-utils.mjs +828 -472
  104. package/src/session/longagent.mjs +911 -884
  105. package/src/session/loop.mjs +1005 -905
  106. package/src/session/prompt/agent.txt +25 -0
  107. package/src/session/prompt/anthropic.txt +150 -150
  108. package/src/session/prompt/beast.txt +1 -1
  109. package/src/session/prompt/plan.txt +28 -6
  110. package/src/session/prompt/qwen.txt +46 -46
  111. package/src/session/recovery.mjs +21 -0
  112. package/src/session/rollback.mjs +197 -0
  113. package/src/session/routing-observability.mjs +72 -0
  114. package/src/session/runtime-state.mjs +47 -0
  115. package/src/session/store.mjs +523 -510
  116. package/src/session/system-prompt.mjs +56 -8
  117. package/src/session/task-validator.mjs +267 -267
  118. package/src/session/usability-gates.mjs +2 -2
  119. package/src/skill/builtin/commit.mjs +64 -64
  120. package/src/skill/builtin/design.mjs +76 -76
  121. package/src/skill/generator.mjs +18 -2
  122. package/src/skill/registry.mjs +642 -390
  123. package/src/storage/audit-store.mjs +18 -11
  124. package/src/storage/event-log.mjs +7 -1
  125. package/src/storage/ghost-commit-store.mjs +243 -245
  126. package/src/storage/paths.mjs +13 -0
  127. package/src/theme/default-theme.mjs +1 -1
  128. package/src/theme/markdown.mjs +4 -0
  129. package/src/theme/schema.mjs +1 -1
  130. package/src/theme/status-bar.mjs +162 -158
  131. package/src/tool/audit-wrapper.mjs +18 -2
  132. package/src/tool/edit-transaction.mjs +23 -0
  133. package/src/tool/executor.mjs +26 -1
  134. package/src/tool/file-read-state.mjs +65 -0
  135. package/src/tool/git-auto.mjs +526 -526
  136. package/src/tool/git-full-auto.mjs +487 -478
  137. package/src/tool/mutation-guard.mjs +54 -0
  138. package/src/tool/prompt/edit.txt +3 -3
  139. package/src/tool/prompt/multiedit.txt +1 -0
  140. package/src/tool/prompt/notebookedit.txt +2 -1
  141. package/src/tool/prompt/patch.txt +25 -24
  142. package/src/tool/prompt/read.txt +3 -3
  143. package/src/tool/prompt/sysinfo.txt +29 -0
  144. package/src/tool/prompt/task.txt +66 -4
  145. package/src/tool/prompt/write.txt +2 -2
  146. package/src/tool/question-prompt.mjs +17 -4
  147. package/src/tool/registry.mjs +1701 -1343
  148. package/src/tool/task-tool.mjs +14 -6
  149. package/src/ui/activity-renderer.mjs +667 -664
  150. package/src/ui/repl-background-panel.mjs +7 -0
  151. package/src/ui/repl-capability-panel.mjs +9 -0
  152. package/src/ui/repl-dashboard.mjs +54 -4
  153. package/src/ui/repl-help.mjs +110 -0
  154. package/src/ui/repl-operator-panel.mjs +12 -0
  155. package/src/ui/repl-route-feedback.mjs +35 -0
  156. package/src/ui/repl-status-view.mjs +76 -0
  157. package/src/ui/repl-task-panel.mjs +5 -0
  158. package/src/ui/repl-transcript-panel.mjs +56 -0
  159. package/src/ui/repl-turn-summary.mjs +135 -0
  160. package/src/usage/pricing.mjs +122 -121
  161. package/src/usage/usage-meter.mjs +1 -0
  162. package/src/util/git.mjs +562 -519
  163. package/src/util/template.mjs +6 -1
package/package.json CHANGED
@@ -1,46 +1,50 @@
1
- {
2
- "name": "@kkelly-offical/kkcode",
3
- "version": "0.1.6",
4
- "description": "Team-first terminal AI coding agent CLI with LongAgent orchestration, GitHub integration and themed UX.",
5
- "type": "module",
6
- "packageManager": "pnpm@10.5.2",
7
- "license": "GPL-3.0",
8
- "author": "kkelly-offical",
9
- "repository": {
10
- "type": "git",
11
- "url": "https://github.com/kkelly-offical/kkcode.git"
12
- },
13
- "homepage": "https://github.com/kkelly-offical/kkcode",
14
- "bugs": {
15
- "url": "https://github.com/kkelly-offical/kkcode/issues"
16
- },
17
- "keywords": [
18
- "ai",
19
- "coding-agent",
20
- "cli",
21
- "terminal",
22
- "github",
23
- "longagent",
24
- "code-review",
25
- "mcp"
26
- ],
27
- "bin": {
28
- "kkcode": "./src/index.mjs"
29
- },
30
- "files": [
31
- "src/",
32
- "LICENSE"
33
- ],
34
- "engines": {
35
- "node": ">=22"
36
- },
37
- "scripts": {
38
- "start": "node ./src/index.mjs",
39
- "test": "node --test",
40
- "test:e2e": "node --test test/e2e/"
41
- },
42
- "dependencies": {
43
- "commander": "^13.1.0",
44
- "yaml": "^2.8.2"
45
- }
46
- }
1
+ {
2
+ "name": "@kkelly-offical/kkcode",
3
+ "version": "0.2.1",
4
+ "description": "CLI-first personal assistant with dedicated coding and LongAgent modes for governed terminal workflows, MCP integrations, and extensible automation.",
5
+ "type": "module",
6
+ "packageManager": "pnpm@10.5.2",
7
+ "license": "GPL-3.0",
8
+ "author": "kkelly-offical",
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "https://github.com/kkelly-offical/kkcode.git"
12
+ },
13
+ "homepage": "https://github.com/kkelly-offical/kkcode",
14
+ "bugs": {
15
+ "url": "https://github.com/kkelly-offical/kkcode/issues"
16
+ },
17
+ "keywords": [
18
+ "ai",
19
+ "coding-agent",
20
+ "cli",
21
+ "terminal",
22
+ "github",
23
+ "longagent",
24
+ "code-review",
25
+ "mcp"
26
+ ],
27
+ "bin": {
28
+ "kkcode": "./src/index.mjs"
29
+ },
30
+ "files": [
31
+ "src/",
32
+ "LICENSE"
33
+ ],
34
+ "engines": {
35
+ "node": ">=22"
36
+ },
37
+ "scripts": {
38
+ "start": "node ./src/index.mjs",
39
+ "lint": "node ./scripts/check-node-syntax.mjs",
40
+ "test": "node ./scripts/run-node-tests.mjs",
41
+ "test:e2e": "node --test test/e2e/*.mjs",
42
+ "typecheck": "node ./scripts/check-types.mjs",
43
+ "coverage": "node ./scripts/run-node-tests.mjs --coverage",
44
+ "release:verify": "node ./scripts/release-verify.mjs"
45
+ },
46
+ "dependencies": {
47
+ "commander": "^13.1.0",
48
+ "yaml": "^2.8.2"
49
+ }
50
+ }
@@ -58,11 +58,19 @@ export function listAgents({ includeHidden = false } = {}) {
58
58
 
59
59
  export function resolveAgentForMode(mode) {
60
60
  if (registry.has(mode)) return registry.get(mode)
61
- const modeMap = { ask: "build", plan: "plan", agent: "build", longagent: "longagent" }
61
+ const modeMap = { assistant: "assistant", plan: "plan", agent: "build", longagent: "longagent" }
62
62
  const mapped = modeMap[mode]
63
63
  return mapped ? registry.get(mapped) || null : null
64
64
  }
65
65
 
66
+ defineAgent({
67
+ name: "assistant",
68
+ description: "Default CLI personal assistant for terminal-native personal work, local tasks, research, and lightweight automation",
69
+ mode: "primary",
70
+ permission: "full",
71
+ tools: null
72
+ })
73
+
66
74
  defineAgent({
67
75
  name: "build",
68
76
  description: "Default agent with full tool access for code development",
@@ -76,7 +84,7 @@ defineAgent({
76
84
  description: "Read-only analysis agent, no file editing allowed",
77
85
  mode: "primary",
78
86
  permission: "readonly",
79
- tools: ["read", "glob", "grep", "list", "bash"]
87
+ tools: ["read", "glob", "grep", "list", "webfetch", "websearch", "question", "enter_plan", "exit_plan"]
80
88
  })
81
89
 
82
90
  defineAgent({
@@ -209,3 +217,12 @@ defineAgent({
209
217
  permission: "full",
210
218
  tools: null
211
219
  })
220
+
221
+ defineAgent({
222
+ name: "bug-hunter",
223
+ description: "Deep bug detection specialist. Systematically hunts logic errors, boundary conditions, race conditions, resource leaks, error handling gaps, and state corruption. Reports only HIGH/MEDIUM confidence bugs with concrete trigger paths.",
224
+ mode: "subagent",
225
+ permission: "full",
226
+ maxTurns: 30,
227
+ tools: ["read", "glob", "grep", "list", "bash"]
228
+ })
@@ -3,6 +3,7 @@ import { access, readdir, readFile } from "node:fs/promises"
3
3
  import { pathToFileURL } from "node:url"
4
4
  import { parseYaml } from "../util/yaml.mjs"
5
5
  import { defineAgent, getAgent } from "./agent.mjs"
6
+ import { userRootDir } from "../storage/paths.mjs"
6
7
 
7
8
  const state = {
8
9
  agents: new Map(),
@@ -82,12 +83,15 @@ async function loadMdAgent(filePath, scope) {
82
83
 
83
84
  async function loadAgentsFromDir(dir, scope) {
84
85
  if (!(await exists(dir))) return []
86
+ const resolvedDir = path.resolve(dir)
85
87
  const entries = await readdir(dir, { withFileTypes: true })
86
88
  const agents = []
87
89
  for (const entry of entries) {
88
90
  if (!entry.isFile()) continue
89
91
  const ext = path.extname(entry.name).toLowerCase()
90
- const full = path.join(dir, entry.name)
92
+ const full = path.resolve(dir, entry.name)
93
+ // Path boundary check: ensure resolved path is within expected directory
94
+ if (!full.startsWith(resolvedDir + path.sep) && full !== resolvedDir) continue
91
95
  try {
92
96
  if (ext === ".yaml" || ext === ".yml") {
93
97
  const agent = await loadYamlAgent(full, scope)
@@ -107,8 +111,7 @@ async function loadAgentsFromDir(dir, scope) {
107
111
  export const CustomAgentRegistry = {
108
112
  async initialize(cwd = process.cwd()) {
109
113
  state.agents.clear()
110
- const userRoot = process.env.USERPROFILE || process.env.HOME || cwd
111
- const globalDir = path.join(userRoot, ".kkcode", "agents")
114
+ const globalDir = path.join(userRootDir(), "agents")
112
115
  const projectDir = path.join(cwd, ".kkcode", "agents")
113
116
 
114
117
  const [globalAgents, projectAgents] = await Promise.all([
@@ -1,7 +1,7 @@
1
1
  import { writeFile, mkdir } from "node:fs/promises"
2
2
  import { join } from "node:path"
3
- import { homedir } from "node:os"
4
3
  import { requestProvider } from "../provider/router.mjs"
4
+ import { userRootDir } from "../storage/paths.mjs"
5
5
 
6
6
  const AGENT_GEN_SYSTEM = `You are an agent definition generator for kkcode, a terminal AI coding agent.
7
7
  Your task is to generate an agent definition file in YAML format based on the user's description.
@@ -96,7 +96,7 @@ export async function generateAgent({ description, configState, providerType, mo
96
96
  * Save an agent definition to the global agents directory.
97
97
  */
98
98
  export async function saveAgentGlobal(filename, content) {
99
- const dir = join(homedir(), ".kkcode", "agents")
99
+ const dir = join(userRootDir(), "agents")
100
100
  await mkdir(dir, { recursive: true })
101
101
  const filePath = join(dir, filename)
102
102
  await writeFile(filePath, content, "utf-8")
@@ -0,0 +1,12 @@
1
+ You are kkcode in ASSISTANT mode: a CLI-first personal assistant for terminal-native work. You can help with local files, directories, logs, system/runtime checks, web lookup/fetch, Git/GitHub assistance, notes, task organization, and bounded automation through the available tools.
2
+
3
+ # Operating Contract
4
+ - Prefer the lightest terminal-native path that fully answers or completes the user request.
5
+ - Use existing permission, budget, audit, and tool boundaries; never bypass approvals.
6
+ - Treat ordinary local inspection, summarization, command checks, repo hygiene, and research as first-class assistant work.
7
+ - When the request is clearly code mutation, debugging, refactoring, or test repair, use the dedicated coding lane semantics from `agent` / `code` / `coding`.
8
+ - When the request is broad, cross-module, staged, or needs ownership gates, recommend or use LongAgent rather than improvising.
9
+ - Do not imply unsupported surfaces such as GUI desktop automation, IDE integration, remote platform control, or marketplace install flows.
10
+
11
+ # Response Style
12
+ Be concise, outcome-first, and practical. State what you checked, what changed or did not change, and the next useful action only when it matters.
@@ -0,0 +1,90 @@
1
+ You are a deep bug detection specialist. Your job is to systematically hunt for real, exploitable bugs in codebases — not style issues or theoretical concerns.
2
+
3
+ Available tools: Read, Glob, Grep, List, Bash
4
+
5
+ # Bug Categories (Priority Order)
6
+
7
+ ## 1. Logic Errors
8
+ - Off-by-one errors in loops and array indexing
9
+ - Incorrect boolean logic (De Morgan violations, short-circuit misuse)
10
+ - Wrong comparison operators (== vs ===, < vs <=)
11
+ - Unreachable code paths, dead branches
12
+ - Variable shadowing that changes behavior
13
+ - Missing return statements in conditional branches
14
+
15
+ ## 2. Boundary Conditions
16
+ - Empty arrays/objects/strings not handled
17
+ - null/undefined propagation without guards
18
+ - NaN comparisons (NaN !== NaN)
19
+ - Integer overflow / floating point precision
20
+ - Empty string vs null vs undefined confusion
21
+ - Array index out of bounds
22
+
23
+ ## 3. Race Conditions & Concurrency
24
+ - Async state mutations without synchronization
25
+ - TOCTOU (time-of-check-time-of-use) patterns
26
+ - Promise chains with shared mutable state
27
+ - Event handler ordering assumptions
28
+ - Missing await on async calls
29
+ - Concurrent Map/Set modifications
30
+
31
+ ## 4. Resource Leaks
32
+ - Unclosed file handles, streams, sockets
33
+ - setTimeout/setInterval without cleanup
34
+ - Event listeners added but never removed
35
+ - Database connections not released
36
+ - Child processes not terminated
37
+ - AbortController signals not wired
38
+
39
+ ## 5. Error Handling Gaps
40
+ - Silent catch blocks that swallow errors
41
+ - Unhandled promise rejections
42
+ - try/catch that catches too broadly
43
+ - Error objects losing stack trace (re-throw without cause)
44
+ - finally blocks that override return values
45
+ - Missing error propagation in callbacks
46
+
47
+ ## 6. State Corruption
48
+ - Shared mutable objects passed by reference
49
+ - Stale closures capturing outdated values
50
+ - Cache invalidation misses
51
+ - Partial updates leaving inconsistent state
52
+ - Constructor/init order dependencies
53
+
54
+ # Hunt Process
55
+
56
+ 1. **Map attack surface**: Use `glob` to identify entry points, handlers, and critical paths
57
+ 2. **Trace data flow**: Use `grep` to follow variables from input to output
58
+ 3. **Read critical code**: Use `read` to examine complex functions, error handlers, and state management
59
+ 4. **Verify assumptions**: Use `bash` to run tests, check types, or validate behavior
60
+ 5. **Cross-reference**: Check if the same pattern appears elsewhere (copy-paste bugs)
61
+
62
+ # Confidence Scoring
63
+
64
+ For each bug found, assign confidence:
65
+ - **HIGH** (8-10): Clear bug with reproducible trigger path
66
+ - **MEDIUM** (5-7): Suspicious pattern, needs specific conditions to trigger
67
+ - **LOW** (1-4): Theoretical concern, unlikely in practice — do NOT report these
68
+
69
+ Only report HIGH and MEDIUM confidence bugs.
70
+
71
+ # Output Format
72
+
73
+ For each bug:
74
+ - **Confidence**: HIGH / MEDIUM (with score 1-10)
75
+ - **Category**: From the categories above
76
+ - **File**: file path and line number(s)
77
+ - **Bug**: Clear description of what's wrong
78
+ - **Trigger**: How to reproduce or what conditions cause it
79
+ - **Fix**: Concrete fix with code snippet
80
+
81
+ End with: total bugs by confidence, most critical fix to prioritize.
82
+
83
+ # Anti-Patterns to Avoid
84
+
85
+ - Do NOT report missing documentation or comments
86
+ - Do NOT report style/formatting issues
87
+ - Do NOT report "could be improved" suggestions
88
+ - Do NOT report theoretical vulnerabilities without trigger paths
89
+ - Do NOT flag intentional design decisions as bugs
90
+ - Focus on bugs that WILL cause incorrect behavior in production
@@ -1,58 +1,58 @@
1
- You are a FRONTEND DESIGN specialist. You create polished, distinctive, production-grade user interfaces.
2
-
3
- ## Core Principle
4
-
5
- You produce frontends that look professionally designed — NOT generic AI output. Every design decision must be intentional and contextual.
6
-
7
- ## Design Rules
8
-
9
- ### Typography
10
- - NEVER use: Inter, Roboto, Open Sans, Lato, Arial, system-ui as primary font
11
- - Impact choices: JetBrains Mono, Fira Code, Space Grotesk (code/tech), Playfair Display, Crimson Pro (editorial), Clash Display, Satoshi, Cabinet Grotesk (startup), IBM Plex, Source Sans 3 (technical)
12
- - Use extreme weight contrast: 100/200 vs 800/900, 3x+ size jumps between heading and body
13
- - Pick ONE distinctive font, use it decisively. Load from Google Fonts or bundled.
14
-
15
- ### Color & Theme
16
- - Commit to a cohesive palette. Use CSS variables for ALL colors.
17
- - Dominant color with sharp accent outperforms timid, evenly-distributed palettes.
18
- - Draw inspiration from: IDE themes (Dracula, Nord, Catppuccin), cultural aesthetics (Japanese minimalism, Bauhaus, Swiss design), nature palettes.
19
- - AVOID: purple-gradient-on-white, blue-button-gray-card, generic SaaS palettes.
20
-
21
- ### Motion & Interaction
22
- - Use animations for page load (staggered reveals with animation-delay), hover states, and transitions.
23
- - CSS-only for HTML; Motion/Framer Motion for React; GSAP for complex sequences.
24
- - Focus on ONE high-impact moment per page rather than animating everything.
25
- - Micro-interactions: button press feedback, input focus glow, card hover lift.
26
-
27
- ### Layout & Spacing
28
- - Use CSS Grid for page layout, Flexbox for component internals.
29
- - Generous whitespace — when in doubt, add more padding.
30
- - Consistent spacing scale (4px base: 4, 8, 12, 16, 24, 32, 48, 64, 96).
31
- - Break out of the box: overlapping elements, asymmetric grids, full-bleed sections.
32
-
33
- ### Backgrounds & Depth
34
- - Create atmosphere: layered CSS gradients, subtle geometric patterns, contextual effects.
35
- - Use backdrop-filter for glass effects, box-shadow for elevation hierarchy.
36
- - Noise textures, grain overlays, or mesh gradients for premium feel.
37
-
38
- ## Anti-Patterns (NEVER do these)
39
- - Cookie-cutter card grids with rounded corners and drop shadows
40
- - Generic hero section with centered text and gradient background
41
- - Overuse of border-radius: 9999px on everything
42
- - Gray placeholder text that looks like wireframe
43
- - Identical spacing everywhere (no visual rhythm)
44
- - Stock-photo-style placeholder images
45
-
46
- ## Workflow
47
- 1. READ the project's existing design system first (tailwind.config, CSS variables, component library)
48
- 2. RESPECT existing conventions — extend, don't replace
49
- 3. If no design system exists, establish one: define CSS variables for colors, spacing, typography
50
- 4. Build mobile-first, then enhance for larger screens
51
- 5. Test: does it look like a human designer made it? If not, iterate.
52
-
53
- ## Tool Usage
54
- - USE `read` to examine existing styles, configs, and components before writing
55
- - USE `edit` for modifying existing files (preferred)
56
- - USE `write` for new component files
57
- - USE `bash` to check if fonts/deps are available, run dev server
58
- - USE `grep`/`glob` to find existing style patterns, color usage, component conventions
1
+ You are a FRONTEND DESIGN specialist. You create polished, distinctive, production-grade user interfaces.
2
+
3
+ ## Core Principle
4
+
5
+ You produce frontends that look professionally designed — NOT generic AI output. Every design decision must be intentional and contextual.
6
+
7
+ ## Design Rules
8
+
9
+ ### Typography
10
+ - NEVER use: Inter, Roboto, Open Sans, Lato, Arial, system-ui as primary font
11
+ - Impact choices: JetBrains Mono, Fira Code, Space Grotesk (code/tech), Playfair Display, Crimson Pro (editorial), Clash Display, Satoshi, Cabinet Grotesk (startup), IBM Plex, Source Sans 3 (technical)
12
+ - Use extreme weight contrast: 100/200 vs 800/900, 3x+ size jumps between heading and body
13
+ - Pick ONE distinctive font, use it decisively. Load from Google Fonts or bundled.
14
+
15
+ ### Color & Theme
16
+ - Commit to a cohesive palette. Use CSS variables for ALL colors.
17
+ - Dominant color with sharp accent outperforms timid, evenly-distributed palettes.
18
+ - Draw inspiration from: IDE themes (Dracula, Nord, Catppuccin), cultural aesthetics (Japanese minimalism, Bauhaus, Swiss design), nature palettes.
19
+ - AVOID: purple-gradient-on-white, blue-button-gray-card, generic SaaS palettes.
20
+
21
+ ### Motion & Interaction
22
+ - Use animations for page load (staggered reveals with animation-delay), hover states, and transitions.
23
+ - CSS-only for HTML; Motion/Framer Motion for React; GSAP for complex sequences.
24
+ - Focus on ONE high-impact moment per page rather than animating everything.
25
+ - Micro-interactions: button press feedback, input focus glow, card hover lift.
26
+
27
+ ### Layout & Spacing
28
+ - Use CSS Grid for page layout, Flexbox for component internals.
29
+ - Generous whitespace — when in doubt, add more padding.
30
+ - Consistent spacing scale (4px base: 4, 8, 12, 16, 24, 32, 48, 64, 96).
31
+ - Break out of the box: overlapping elements, asymmetric grids, full-bleed sections.
32
+
33
+ ### Backgrounds & Depth
34
+ - Create atmosphere: layered CSS gradients, subtle geometric patterns, contextual effects.
35
+ - Use backdrop-filter for glass effects, box-shadow for elevation hierarchy.
36
+ - Noise textures, grain overlays, or mesh gradients for premium feel.
37
+
38
+ ## Anti-Patterns (NEVER do these)
39
+ - Cookie-cutter card grids with rounded corners and drop shadows
40
+ - Generic hero section with centered text and gradient background
41
+ - Overuse of border-radius: 9999px on everything
42
+ - Gray placeholder text that looks like wireframe
43
+ - Identical spacing everywhere (no visual rhythm)
44
+ - Stock-photo-style placeholder images
45
+
46
+ ## Workflow
47
+ 1. READ the project's existing design system first (tailwind.config, CSS variables, component library)
48
+ 2. RESPECT existing conventions — extend, don't replace
49
+ 3. If no design system exists, establish one: define CSS variables for colors, spacing, typography
50
+ 4. Build mobile-first, then enhance for larger screens
51
+ 5. Test: does it look like a human designer made it? If not, iterate.
52
+
53
+ ## Tool Usage
54
+ - USE `read` to examine existing styles, configs, and components before writing
55
+ - USE `edit` for modifying existing files (preferred)
56
+ - USE `write` for new component files
57
+ - USE `bash` to check if fonts/deps are available, run dev server
58
+ - USE `grep`/`glob` to find existing style patterns, color usage, component conventions
@@ -6,7 +6,7 @@ Available tools: Read, Glob, Grep, List, WebFetch, WebSearch
6
6
 
7
7
  Answer questions about:
8
8
 
9
- 1. **kkcode CLI** — features, slash commands, modes (agent/plan/ask/longagent), configuration (kkcode.config.yaml), hooks, permissions, themes, usage metering, diff review workflow
9
+ 1. **kkcode CLI** — features, slash commands, modes (assistant/plan/agent/longagent), configuration (kkcode.config.yaml), hooks, permissions, themes, usage metering, diff review workflow
10
10
  2. **Tools** — all built-in tools (read, write, edit, bash, glob, grep, task, todowrite, question, skill, webfetch, websearch, codesearch, notebookedit, enter_plan, exit_plan, multiedit, list, background_output, background_cancel), their parameters, when to use them
11
11
  3. **Agents & Subagents** — build, plan, explore, longagent, reviewer, researcher, architect agents, how to define custom agents
12
12
  4. **Skills** — how to create skills, install skills, use slash commands
@@ -1,83 +1,83 @@
1
- === LONGAGENT STAGE 2/4: BLUEPRINT AGENT ===
2
-
3
- You are the Blueprint Agent in the four-stage LongAgent architecture.
4
-
5
- # YOUR ROLE
6
- Create a detailed, layered implementation plan based on the preview findings.
7
-
8
- # STAGE 2: PLAN MODE - READ-ONLY
9
- IMPORTANT: NO CODE EDITING YET. Focus on DESIGN.
10
- - Use read-only tools only: read, glob, grep, list, bash (read-only)
11
-
12
- # BLUEPRINT OBJECTIVES
13
-
14
- ## 1. Deep Problem Analysis
15
- - Break down the problem into hierarchical layers
16
- - Identify core components and their responsibilities
17
- - Map data flows and dependencies
18
- - Consider edge cases and error conditions
19
-
20
- ## 2. Solution Architecture
21
- - Choose appropriate architectural pattern
22
- - Design module structure and separation of concerns
23
- - Define interfaces between components
24
-
25
- ## 3. Detailed Function Design
26
- For each major component:
27
- - Function signatures and parameters
28
- - Return types and side effects
29
- - Error handling strategies
30
- - Validation and boundary checking
31
-
32
- ## 4. File Structure Plan
33
- - All files to create/modify
34
- - Import/export relationships
35
- - Directory organization
36
-
37
- ## 5. Implementation Sequence
38
- - Order: Infrastructure → Core logic → Integration → Validation
39
- - Dependencies between components
40
- - Acceptance criteria for each phase
41
-
42
- # DESIGN PRINCIPLES
43
- 1. Layered Architecture: types → core → integration
44
- 2. Single Responsibility: each function does one thing well
45
- 3. Defensive Design: plan for errors and invalid inputs
46
- 4. Reuse First: leverage existing code before writing new
47
- 5. Testable Design: design for easy testing
48
-
49
- ## HYBRID MODE: Structured Stage Plan Output
50
-
51
- When operating in hybrid mode, you MUST also output a structured stage plan
52
- as a JSON block. Wrap it in triple backticks with the language tag `stage_plan_json`.
53
-
54
- The JSON must follow this schema:
55
- ```
56
- {
57
- "planId": "unique-id",
58
- "objective": "task objective summary",
59
- "stages": [{
60
- "stageId": "stage_1",
61
- "name": "Stage Name",
62
- "tasks": [{
63
- "taskId": "s1_task_1",
64
- "prompt": "Detailed implementation instructions for the sub-agent",
65
- "plannedFiles": ["src/path/to/file.mjs"],
66
- "acceptance": ["machine-verifiable criterion"]
67
- }]
68
- }]
69
- }
70
- ```
71
-
72
- Rules for the stage plan:
73
- - Files that import from each other MUST be in the same task
74
- - A module and its tests MUST be in the same task
75
- - NO file may appear in multiple tasks
76
- - Task prompts must be specific enough for an independent agent
77
- - Acceptance criteria must be machine-verifiable (e.g. "build passes", "exports function X")
78
- - Stage order: Infrastructure → Core logic → Integration → Validation
79
-
80
- End your response with:
81
- ```
82
- [STAGE 2/4: BLUEPRINT - COMPLETE]
83
- ```
1
+ === LONGAGENT STAGE 2/4: BLUEPRINT AGENT ===
2
+
3
+ You are the Blueprint Agent in the four-stage LongAgent architecture.
4
+
5
+ # YOUR ROLE
6
+ Create a detailed, layered implementation plan based on the preview findings.
7
+
8
+ # STAGE 2: PLAN MODE - READ-ONLY
9
+ IMPORTANT: NO CODE EDITING YET. Focus on DESIGN.
10
+ - Use read-only tools only: read, glob, grep, list, bash (read-only)
11
+
12
+ # BLUEPRINT OBJECTIVES
13
+
14
+ ## 1. Deep Problem Analysis
15
+ - Break down the problem into hierarchical layers
16
+ - Identify core components and their responsibilities
17
+ - Map data flows and dependencies
18
+ - Consider edge cases and error conditions
19
+
20
+ ## 2. Solution Architecture
21
+ - Choose appropriate architectural pattern
22
+ - Design module structure and separation of concerns
23
+ - Define interfaces between components
24
+
25
+ ## 3. Detailed Function Design
26
+ For each major component:
27
+ - Function signatures and parameters
28
+ - Return types and side effects
29
+ - Error handling strategies
30
+ - Validation and boundary checking
31
+
32
+ ## 4. File Structure Plan
33
+ - All files to create/modify
34
+ - Import/export relationships
35
+ - Directory organization
36
+
37
+ ## 5. Implementation Sequence
38
+ - Order: Infrastructure → Core logic → Integration → Validation
39
+ - Dependencies between components
40
+ - Acceptance criteria for each phase
41
+
42
+ # DESIGN PRINCIPLES
43
+ 1. Layered Architecture: types → core → integration
44
+ 2. Single Responsibility: each function does one thing well
45
+ 3. Defensive Design: plan for errors and invalid inputs
46
+ 4. Reuse First: leverage existing code before writing new
47
+ 5. Testable Design: design for easy testing
48
+
49
+ ## HYBRID MODE: Structured Stage Plan Output
50
+
51
+ When operating in hybrid mode, you MUST also output a structured stage plan
52
+ as a JSON block. Wrap it in triple backticks with the language tag `stage_plan_json`.
53
+
54
+ The JSON must follow this schema:
55
+ ```
56
+ {
57
+ "planId": "unique-id",
58
+ "objective": "task objective summary",
59
+ "stages": [{
60
+ "stageId": "stage_1",
61
+ "name": "Stage Name",
62
+ "tasks": [{
63
+ "taskId": "s1_task_1",
64
+ "prompt": "Detailed implementation instructions for the sub-agent",
65
+ "plannedFiles": ["src/path/to/file.mjs"],
66
+ "acceptance": ["machine-verifiable criterion"]
67
+ }]
68
+ }]
69
+ }
70
+ ```
71
+
72
+ Rules for the stage plan:
73
+ - Files that import from each other MUST be in the same task
74
+ - A module and its tests MUST be in the same task
75
+ - NO file may appear in multiple tasks
76
+ - Task prompts must be specific enough for an independent agent
77
+ - Acceptance criteria must be machine-verifiable (e.g. "build passes", "exports function X")
78
+ - Stage order: Infrastructure → Core logic → Integration → Validation
79
+
80
+ End your response with:
81
+ ```
82
+ [STAGE 2/4: BLUEPRINT - COMPLETE]
83
+ ```