feat(keywords): Magic Keyword System — Master Plan (issue #391) by quangdang46 · Pull Request #393 · quangdang46/jcode

quangdang46 · 2026-06-05T18:50:34Z

Summary

Master implementation plan for the Magic Keyword System — full keyword detection + workflow handlers for natural language mode activation.

Closes #391

What This Plan Covers

1. Keyword Detection (50+ triggers)

Natural language triggers (not just $prefix)
8-stage sanitization (code blocks, URLs, quotes, system echoes)
Intent disambiguation (informational vs activation vs diagnostic)
Multilingual: EN, KO, JA, ZH, VI (128 triggers total)
Task size classification (suppress heavy modes for simple tasks)
Priority-based conflict resolution

2. Workflow Handlers (14 modes)

Priority	Keyword	Workflow
11	`$ralplan`	Consensus planning (plan → adversarial review → approve)
10	`$ultrawork`	Parallel execution (spawn 4 sub-agents)
10	`$ultragoal`	Durable goal tracking with token budget
9	`canceljcode`	Cancel all modes + tasks
8	`$ultraqa`	QA cycling (implement → test → fix → repeat)
8	`$deep-interview`	Requirements gathering (Q&A → ambiguity scoring)
7	`$ultrathink`	Extended thinking (deep reasoning)
7	`$deepsearch`	Multi-strategy codebase search
7	`$tdd`	Test-driven development
6	`$code-review`	Code review agent
6	`$security-review`	Security audit (OWASP Top 10)
6	`$analyze`	Deep structured analysis
5	`$wiki`	Documentation lookup
5	ai-slop-cleaner	Fix AI-generated low-quality code

3. Additional Features

Persistent mode state (.jcode/state/modes.toml)
Visual effects (rainbow highlighting, shimmer animation, toast notifications)
Per-model prompt variants (Claude, GPT, Gemini)
State machines per workflow
Error handling per workflow
Edge case handling (10 scenarios)

Plan Location

Full plan: docs/keyword-system-master-plan.md (2,209 lines)

Implementation Phases

Detection Engine — registry, sanitizer, detector, intent, task_size, conflict
State + Prompt Injection — TOML persistence, prompt_builder, prompting.rs integration
Core Workflows — ultrawork, deep-interview, tdd, code-review, ultrathink
Extended Workflows — ultragoal, ultraqa, ralplan, security, search, analyze, wiki, slop, cancel
TUI Effects — rainbow, shimmer, toast, mode indicator
Config + Polish

Estimate

~6,080 lines of new/modified code across 27 new files + 8 modified files.

For Implementer

Start with Phase 1 (Detection Engine) in crates/jcode-keywords/. The plan has exact Rust code snippets for every component. Follow the phases in order — each phase builds on the previous one.

Comprehensive 2,209-line implementation plan for the magic keyword system: - 50+ NL keyword triggers with sanitization, intent disambiguation, multilingual - 14 workflow handlers (ultrawork, ralplan, tdd, code-review, etc.) - Persistent mode state (TOML) - Visual effects (rainbow, shimmer, toast) - Task size classification + cancel system Research: oh-my-codex, oh-my-openagent, oh-my-claudecode, claude-code, codebuff, oh-my-pi Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Move clap Args::try_parse() to main() before rustls crypto provider, tokio runtime, logging, and telemetry initialization. For --help and --version invocations, clap prints and exits without any heavy setup. Benchmark results (macOS, 10 runs): --help: 17.94ms -> 7.89ms median (-56%) --version: 17.66ms -> 7.82ms median (-56%)

…ction (#391) New crate jcode-keywords (~1,845 lines) implementing the magic keyword system: - Detection engine: 14 keyword entries with aliases, multilingual triggers (EN/KO/JA/ZH/VI), fuzzy Levenshtein matching, overlap filtering - Mode state: TOML persistence at .jcode/state/modes.toml, auto-deactivate after configurable turn count - Prompt injection: active modes injected into system prompt dynamic_part - Task size classification: suppress heavy workflows for simple tasks - Conflict detection: warn about incompatible mode combinations - 14 workflow handlers: ultrawork, ultragoal, ultraqa, ralplan, deep-interview, tdd, code-review, security-review, ultrathink, deepsearch, analyze, wiki, ai-slop-cleaner, cancel - Visual effects: rainbow highlight computation for TUI rendering Integration: keyword detection wired into app-core prompting.rs, detects keywords in latest user message and injects mode prompts. 40/40 tests pass, workspace compiles clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

#391) Phase 1-7: Full workflow execution implementation. ## WorkflowHandler Trait Enhancement - Added WorkflowContext (user_input, working_dir, session_id, mode_state, metadata) - Added WorkflowAction enum (InjectReminder, SpawnAgent, SpawnParallel, AskUser, Continue, Complete, ContinueWithMetadata) - Added SpawnSpec and SpawnResult types - Added execute() and on_turn_complete() methods to WorkflowHandler trait ## New Modules - spawn.rs: Sub-agent spawning utility (spawn_agent, spawn_parallel, aggregate_results, spawn_with_retry) - executor.rs: Workflow execution engine (execute_active_workflows, process_turn_response, build_workflow_prompt) ## State Enhancement - Added metadata: HashMap<String, String> field to ActiveMode for workflow-specific state ## 14 Workflow Implementations ### Tier 1: Prompt-Only - ultrathink: Deep reasoning instructions, single-turn completion - analyze: Structured analysis with findings format - wiki: Documentation search strategy - ai-slop-cleaner: AI code quality improvement checklist ### Tier 2: Sub-Agent Spawning - ultrawork: Parallel sub-agent spawning (4 agents) with retry - code-review: Reviewer agent spawn with OWASP checklist - security-review: Security auditor agent spawn - deepsearch: Parallel search agents (text, structural, semantic) ### Tier 3: Loop Orchestration - ultraqa: implement → test → fix cycle (max 5 iterations) - tdd: red → green → refactor cycle per behavior - ralplan: plan → review → revise → approve → execute ### Tier 4: Interactive - deep-interview: Q&A with ambiguity scoring (threshold < 3) ### Tier 5: State Management - ultragoal: Durable goal tracking with token budget ### Tier 6: System Action - cancel: Clear all modes, return to normal 49/40 tests pass, workspace compiles clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

quangdang46 · 2026-06-06T03:56:26Z

Keyword Workflow Execution — Fix Plan (Post-Review)

Based on 4-reviewer swarm review of PR #393. 17 findings across intent, security, performance, and contracts.

Critical (fix before merge)

C1. No action dispatch — execution engine is inert

Problem: execute_active_workflows(), process_turn_response(), build_workflow_prompt() are exported but zero callers exist. WorkflowAction variants are produced but never consumed.
Fix:

Wire execute_active_workflows into prompting.rs after keyword detection
Wire process_turn_response after LLM response in turn loop
Replace build_keyword_prompt with build_workflow_prompt
Implement action dispatch: match on WorkflowAction variants and execute

C2. ContinueWithMetadata metadata never persisted

Problem: Executor takes &ModeState (immutable), structurally cannot write back. Phase-based workflows stuck forever.
Fix:

Caller matches on ContinueWithMetadata, updates active_mode.metadata
Call save_state() after each metadata update
Option B is cleaner: keep jcode-keywords read-only, persistence in app-core

High (fix soon)

H1. Sub-agent spawn storm — no re-spawn guard

Problem: deepsearch.execute() unconditionally spawns 3 agents every turn. No guard.
Fix: Add metadata guard check (like ultrawork's ultrawork_results check)

H2. Prompt injection via unsanitized user_input

Problem: ctx.user_input interpolated verbatim into sub-agent prompts.
Fix: Wrap in <user_request>...</user_request> delimiters in all handlers

H3. ContinueWithMetadata discards pre-existing metadata

Problem: ralplan/tdd/ultraqa create HashMap::new(), discarding previous metadata.
Fix: Clone ctx.metadata first, then modify (like ultragoal does)

H4. execute() phase advance logic inverted

Problem: execute() advances phase, on_turn_complete() checks wrong phase.
Fix: Move phase advance to on_turn_complete() instead of execute()

H5. Tier 1 handlers auto-complete after one turn

Problem: ultrathink/analyze/wiki/ai-slop-cleaner/code-review/security-review return Complete unconditionally.
Fix: Return Continue (trait default), defer to turn-limit expiration

H6. get_handler() allocates 14 Boxes per call

Problem: all_handlers() heap-allocates 14 Box on every call.
Fix: Use match on WorkflowKind returning &'static dyn WorkflowHandler

H7. spawn_parallel silently drops JoinErrors

Problem: if let Ok(result) = handle.await discards panics.
Fix: Log JoinError, include synthetic SpawnResult { success: false }

H8. String-based signal detection is fragile

Problem: response.contains("green") — "green" is common English word.
Fix: Use structured markers like [PHASE:REFACTORED]

H9. No tests for execute()/on_turn_complete()

Problem: Zero tests for phase state machines.
Fix: Add unit tests for each handler with various metadata states

Medium (fix if time permits)

#	Issue	Fix
M1	Two overlapping prompt builders	Deprecate `build_keyword_prompt`
M2	TUI path not wired	Wire keyword detection in `turn_memory.rs`
M3	extract_ambiguity_score matches broadly	Require "ambiguity" on same line
M4	spawn.rs stub with tokio dep	Remove or feature-gate
M5	SpawnSpec intermediate allocation	Construct SpawnAgent directly
M6	save_state swallows errors	Log warning on failure

Implementation Order

Phase 1: C1 + C2 (action dispatch + metadata persistence)
Phase 2: H1 + H3 + H4 + H5 (fix handler logic)
Phase 3: H2 + H6 + H7 + H8 (security + performance)
Phase 4: H9 (tests)
Phase 5: M1-M6 (polish)

Files to Modify

File	Changes
`crates/jcode-app-core/src/agent/prompting.rs`	Wire execute_active_workflows, action dispatch
`crates/jcode-keywords/src/workflow/mod.rs`	Replace get_handler with match
`crates/jcode-keywords/src/workflow/executor.rs`	Fix metadata persistence, deprecate build_keyword_prompt
`crates/jcode-keywords/src/workflow/deepsearch.rs`	Add re-spawn guard
`crates/jcode-keywords/src/workflow/ultrawork.rs`	Add re-spawn guard
`crates/jcode-keywords/src/workflow/ralplan.rs`	Fix metadata clone, phase advance
`crates/jcode-keywords/src/workflow/tdd.rs`	Fix metadata clone, phase advance
`crates/jcode-keywords/src/workflow/ultraqa.rs`	Fix metadata clone, phase advance
`crates/jcode-keywords/src/workflow/deep_interview.rs`	Fix ambiguity score extraction
`crates/jcode-keywords/src/workflow/ultrathink.rs`	Return Continue instead of Complete
`crates/jcode-keywords/src/workflow/analyze.rs`	Return Continue instead of Complete
`crates/jcode-keywords/src/workflow/wiki.rs`	Return Continue instead of Complete
`crates/jcode-keywords/src/workflow/ai_slop_cleaner.rs`	Return Continue instead of Complete
`crates/jcode-keywords/src/workflow/code_review.rs`	Remove SpawnSpec intermediate, wrap user_input
`crates/jcode-keywords/src/workflow/security_review.rs`	Remove SpawnSpec intermediate, wrap user_input
`crates/jcode-keywords/src/workflow/spawn.rs`	Fix JoinError handling
`crates/jcode-keywords/src/state.rs`	Log save_state errors

Estimated: ~500 lines modified

…rsistence, handler logic (#391) ## Critical Fixes - Wire execute_active_workflows + apply_actions + build_workflow_prompt into prompting.rs - Add metadata persistence: ContinueWithMetadata now writes back to ActiveMode.metadata - Replace build_keyword_prompt with build_workflow_prompt (deprecates old prompt builder) ## High Fixes - get_handler() now uses match-based static dispatch (zero allocations) - WorkflowContext borrows mode_state instead of cloning (no more N² clones) - User input wrapped in <user_request> delimiters (prompt injection prevention) - spawn_parallel now handles JoinErrors instead of silently dropping - Tier 1 handlers (ultrathink, analyze, wiki, ai-slop-cleaner) return Continue (defer to turn-limit) - Phase advance moved from execute() to on_turn_complete() (fixes inverted logic) - Metadata cloning fixed in ralplan/tdd/ultraqa (clone first, then modify) - Re-spawn guards added in deepsearch/ultrawork - Structured completion markers: [PHASE:RED_DONE], [PHASE:GREEN_DONE], etc. - extract_ambiguity_score tightened: requires 'ambiguity' keyword + N/10 pattern - extract_progress tightened: requires 'progress' keyword on same line - WorkflowAction::Error variant added for error propagation ## Medium Fixes - spawn.rs: MAX_CONCURRENT cap (4), JoinError logging - cancel.rs: documented as no-op (handled by state::update_modes) - Removed unused imports via cargo fix - Removed unused DEFAULT_TOKEN_BUDGET constant 53 tests pass, workspace compiles clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…tization (#391) ## Critical Fixes - Wire process_turn_response: process PREVIOUS turn's LLM response at start of CURRENT turn (phase transitions, completion markers, ambiguity extraction now work) - Persist metadata to disk: call save_state() after apply_actions() - Log workflow summaries instead of silently discarding ## High Fixes - sanitize_user_input: escape </user_request> delimiter to prevent breakout - apply_actions: insert *_spawned keys after SpawnAgent/SpawnParallel (re-spawn guards now actually trigger) ## Medium Fixes - extract_progress: default to None instead of 10.0 (no false goal completion) - Delete orphaned prompt_builder.rs file - truncate_str: UTF-8 safe truncation (no panics on CJK/emoji) - extract_progress: only update when LLM actually reports progress 53 tests pass, workspace compiles clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

- #5 Memory leak: make keyword registry truly static via OnceLock + Box::leak, eliminating per-detection heap allocations. - #3 truncate_str byte-vs-char bug: rewrite on char_indices so CJK and other multi-byte reminders are truncated by character count and never on a non-char-boundary. - #6 Duplicate save_state + silent TOML parse errors: move the single save to the integration in process_turn; surface parse/IO errors via eprintln instead of silently returning Default. - #4 Empty-input turn-limit decrement: skip the entire keyword pipeline (including the per-mode turn_count increment) when the latest user message has no text content. - #7 Wire task_size::should_suppress into execute_active_workflows and conflict::check_conflicts into the integration; remove dead search_triggers/analyze_triggers from registry. - #1 TUI path gap: extract a single process_turn entry point used by both Agent::build_system_prompt_split and App::build_system_prompt_split so the two paths cannot drift apart. Add jcode-keywords dep to jcode-tui and wire the call. - #2 Spawn actions are still stubbed at the executor level, but apply_actions now returns DeferredSpawn values and the integration logs a clear warning that execution must be wired via SubagentTool. This is a follow-up. - #8 Remove unused serde_json dep from jcode-keywords. - #9 Multi-byte alias slice panic: compute the matched window's byte length from the actual haystack instead of the static alias string, with a non-char-boundary guard in the short-alias path. Tests: 55 keyword tests pass (was 53, +2 for new truncation and multi-byte safety cases; -2 for removed search_triggers_count and analyze_triggers_count).

# Conflicts: # src/lib.rs

quangdang46 and others added 4 commits June 6, 2026 01:50

Tran Quang Dang and others added 5 commits June 6, 2026 11:11

merge: master into feature/keyword-system-391

a865f39

# Conflicts: # src/lib.rs

merge: master into feature/keyword-system-391

620c3f4

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(keywords): Magic Keyword System — Master Plan (issue #391)#393

feat(keywords): Magic Keyword System — Master Plan (issue #391)#393
quangdang46 wants to merge 9 commits into
masterfrom
feature/keyword-system-391

quangdang46 commented Jun 5, 2026

Uh oh!

quangdang46 commented Jun 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

quangdang46 commented Jun 5, 2026

Summary

What This Plan Covers

1. Keyword Detection (50+ triggers)

2. Workflow Handlers (14 modes)

3. Additional Features

Plan Location

Implementation Phases

Estimate

For Implementer

Uh oh!

quangdang46 commented Jun 6, 2026

Keyword Workflow Execution — Fix Plan (Post-Review)

Critical (fix before merge)

C1. No action dispatch — execution engine is inert

C2. ContinueWithMetadata metadata never persisted

High (fix soon)

H1. Sub-agent spawn storm — no re-spawn guard

H2. Prompt injection via unsanitized user_input

H3. ContinueWithMetadata discards pre-existing metadata

H4. execute() phase advance logic inverted

H5. Tier 1 handlers auto-complete after one turn

H6. get_handler() allocates 14 Boxes per call

H7. spawn_parallel silently drops JoinErrors

H8. String-based signal detection is fragile

H9. No tests for execute()/on_turn_complete()

Medium (fix if time permits)

Implementation Order

Files to Modify

Estimated: ~500 lines modified

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant