[WIP] feat: Magic keyword system (NL aliases + priority)

[quangdang46]

Magic Keyword System — Full Implementation Plan

Full plan: .claude/plans/piped-gliding-sun.md (2,209 lines)

What This Adds

1. Keyword Detection — 50+ NL triggers with sanitization, intent disambiguation, multilingual (EN/KO/JA/ZH/VI)
2. Workflow Handlers — 14 full execution workflows (spawn agents, enforce rules, aggregate results)
3. Mode State — persistent across turns/session restarts (.jcode/state/modes.toml)
4. Visual Effects — rainbow highlighting, shimmer animation, toast notifications
5. Task Size Classification — suppress heavy modes for simple tasks
6. Cancel System — canceljcode / stopjcode

Keywords + Workflows

Priority	Keyword	Aliases	Workflow
11	$ralplan	ralplan, consensus plan	ConsensusPlanning (plan → adversarial review → revise → approve)
10	$ultrawork	ulw, uw, parallel, dont stop, must complete	ParallelExecution (spawn 4 sub-agents, coordinate, aggregate)
10	$ultragoal	ultragoal	GoalTracking (durable goal + token budget across turns)
9	canceljcode	stopjcode	CancelAll (stop all modes + cancel tasks)
8	$ultraqa	ultraqa, qa cycle	QACycling (implement → test → fix → repeat)
8	$deep-interview	ouroboros, interview me, gather requirements	RequirementsGathering (ask questions → score ambiguity → threshold)
7	$ultrathink	think hard, think deeply	ExtendedThinking (deep reasoning, single-turn)
7	$deepsearch	search the codebase, find in codebase	CodebaseSearch (multi-strategy search → context map)
7	$tdd	test first, red green	TestDrivenDev (write test → fail → implement → pass)
6	$code-review	code review, review code	CodeReview (spawn reviewer → analyze → report)
6	$security-review	security review, audit security	SecurityReview (OWASP scan → secrets → report)
6	$analyze	deep-analyze, deep analysis	DeepAnalysis (structured analysis → report)
5	$wiki	wiki this, look up docs	DocLookup (local + web docs → summary)
5	ai-slop-cleaner	compound: action + smell word	SlopCleanup (detect + fix AI low-quality code)

Multilingual Triggers

• Search: 64 triggers (EN/KO/JA/ZH/VI)
• Analyze: 64 triggers (EN/KO/JA/ZH/VI)

New Crate: jcode-keywords (~5,700 lines)

crates/jcode-keywords/src/
├── lib.rs, registry.rs, detector.rs, sanitizer.rs
├── intent.rs, task_size.rs, conflict.rs, state.rs
├── prompt_builder.rs, visual.rs
└── workflow/
    ├── mod.rs (WorkflowHandler trait)
    ├── ultrawork.rs, ultragoal.rs, ultraqa.rs
    ├── ralplan.rs, deep_interview.rs, tdd.rs
    ├── code_review.rs, security_review.rs
    ├── ultrathink.rs, deepsearch.rs, analyze.rs
    ├── wiki.rs, ai_slop_cleaner.rs, cancel.rs

Integration Points

• Point C: prompting.rs:build_system_prompt_split() — keyword detection + prompt injection
• TUI: input.rs — rainbow highlighting + shimmer animation
• State: .jcode/state/modes.toml — persistent mode state

6 Implementation Phases

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

Estimate: ~6,080 lines new/modified code

[quangdang46]

Keyword Workflow Execution — Master Plan

Problem

Hiện tại jcode-keywords chỉ có detection + prompt injection (advisory text). 14 workflow handlers chỉ trả về static prompt — không có actual execution logic. Cần implement execution cho từng keyword.

Architecture Analysis

Existing Sub-Agent Mechanisms

Mechanism	File	Pattern	Use Case
SubagentTool	app-core/src/tool/task.rs:148-421	In-process, synchronous, Agent::new_with_session() + run_once_capture()	LLM calls subagent tool
Swarm spawn	app-core/src/server/comm_session.rs:428-644	Server-side, headless session, independent lifecycle	Multi-agent coordination
Agent runtime	jcode-agent-runtime/	Declarative TOML definitions, AgentRegistry	Reusable agent configs

Turn Loop Injection Points

Point	Location	When	What
A	prompting.rs:117-132	Before API call	Keyword detection + prompt injection (DONE)
B	turn_loops.rs:1035-1060	After tool execution, before next loop	Workflow orchestration hooks
C	turn_streaming_mpsc.rs:966-1002	Between tool calls	Soft interrupt injection
D	New: after detection	Before API call	Programmatic sub-agent spawn

Workflow Classification

Tier 1: Prompt-Only (no execution logic needed)

These workflows chỉ cần inject instructions tốt hơn vào system prompt. LLM tự thực hiện.

Workflow	Why Prompt-Only
ultrathink	Single-turn deep reasoning — LLM tự suy nghĩ sâu, không cần orchestration
analyze	Structured analysis — LLM tự examine code và report
wiki	Doc lookup — LLM tự search docs và summarize
ai-slop-cleaner	Detect + fix — LLM tự identify và fix code

Implementation: Cải thiện build_prompt() với detailed step-by-step instructions.

Tier 2: Sub-Agent Spawning (parallel execution)

Cần spawn sub-agents để chạy song song.

Workflow	Spawn Strategy
ultrawork	Spawn 4 sub-agents, each handles independent subtask, aggregate results
code-review	Spawn reviewer agent, analyze code, return report
security-review	Spawn security agent, OWASP scan, return findings
deepsearch	Spawn search agents with different strategies (grep, AST, semantic), merge results

Implementation: WorkflowHandler::execute() spawns sub-agents via SubagentTool pattern.

Tier 3: Loop Orchestration (multi-turn cycles)

Cần orchestrate nhiều turn với iteration.

Workflow	Loop Pattern
ultraqa	implement → test → fix → repeat (max 5 iterations)
tdd	write test → fail → implement → pass → refactor (per behavior)
ralplan	plan → adversarial review → revise → approve (user approval gate)

Implementation: State machine trong ModeState, hook vào turn loop.

Tier 4: Interactive (user interaction required)

Cần user input giữa chừng.

Workflow	Interaction
deep-interview	Ask questions → wait for answers → score ambiguity → repeat until < 3

Implementation: Inject questions as system reminders, track ambiguity score.

Tier 5: State Management (persistent goals)

Cần track state across turns.

Workflow	State
ultragoal	Durable goal + token budget + progress tracking

Implementation: Goal state in .jcode/state/goals.toml.

Tier 6: System Action

Workflow	Action
cancel	Clear all mode state, cancel running tasks

Implementation: Direct state mutation + task cancellation.

Detailed Implementation Plan

Phase 1: WorkflowHandler Trait Enhancement

File: crates/jcode-keywords/src/workflow/mod.rs

/// Execution context passed to workflow handlers.
pub struct WorkflowContext {
    /// The user's original input (with keyword stripped).
    pub user_input: String,
    /// Current session messages.
    pub messages: Vec<Message>,
    /// Working directory.
    pub working_dir: Option<PathBuf>,
    /// Provider for spawning sub-agents.
    pub provider: Arc<dyn Provider>,
    /// Tool registry.
    pub registry: Registry,
    /// Session ID.
    pub session_id: String,
    /// Whether we're in TUI mode.
    pub is_tui: bool,
}

/// Result of workflow execution.
pub enum WorkflowAction {
    /// Inject a system reminder into the current turn.
    InjectReminder(String),
    /// Spawn a sub-agent and wait for result.
    SpawnAgent { prompt: String, system_prompt: String, max_turns: u32 },
    /// Spawn multiple sub-agents in parallel.
    SpawnParallel(Vec<SpawnSpec>),
    /// Ask the user a question (returns to user, resumes next turn).
    AskUser(String),
    /// Continue with normal LLM turn (prompt-only mode).
    Continue,
    /// Workflow complete, deactivate mode.
    Complete(String),
}

pub struct SpawnSpec {
    pub description: String,
    pub prompt: String,
    pub system_prompt: String,
    pub max_turns: u32,
}

/// Enhanced workflow handler trait.
pub trait WorkflowHandler: Send + Sync {
    fn kind(&self) -> WorkflowKind;
    fn build_prompt(&self) -> String;

    /// Execute the workflow. Called at the start of each turn while mode is active.
    fn execute(&self, ctx: &WorkflowContext) -> WorkflowAction {
        // Default: prompt-only mode
        WorkflowAction::Continue
    }

    /// Called after each turn to update workflow state.
    fn on_turn_complete(&self, state: &mut ModeState, response: &str) -> WorkflowAction {
        WorkflowAction::Continue
    }
}

Phase 2: Tier 1 — Prompt-Only Workflows

Enhance build_prompt() with detailed instructions.

ultrathink

Strategy:
1. Break down the problem into components
2. For each component, consider:
   - Edge cases and boundary conditions
   - Trade-offs between approaches
   - Alternative solutions
   - Potential failure modes
3. Synthesize findings into a coherent analysis
4. Provide ranked recommendations with rationale

analyze

Strategy:
1. Identify the scope (file, module, system)
2. Examine structure and architecture
3. Map dependencies and data flow
4. Identify patterns (good and anti-patterns)
5. Assess complexity metrics
6. Generate ranked improvement list

wiki

Strategy:
1. Search local docs: README, AGENTS.md, docs/, .jcode/
2. Search code comments and docstrings
3. Search web documentation if API available
4. Cross-reference multiple sources
5. Summarize with source links

ai-slop-cleaner

Strategy:
1. Scan for redundant comments (restating the code)
2. Find over-abstraction (unnecessary wrappers)
3. Detect dead code (unused imports, variables, functions)
4. Identify verbose patterns (could be simplified)
5. For each issue: explain why it's slop, provide clean replacement

Phase 3: Tier 2 — Sub-Agent Spawning Workflows

ultrawork

Execution flow:

1. Analyze user input → identify independent subtasks (LLM call with analysis prompt)
2. For each subtask (up to 4), spawn sub-agent:
   • Create Agent::new_with_session(provider.fork(), registry.clone(), session, allowed)
   • Set system_prompt to subtask-specific instructions
   • Call agent.run_once_capture(&subtask_prompt)
3. Collect results as they complete
4. If any failed, retry up to 3 times
5. Aggregate results into unified response
6. Inject aggregated result as system reminder

Key code pattern (from SubagentTool):

let child_session = Session::create(working_dir, model);
let allowed = compute_allowed_tools(agent_def);
let mut agent = Agent::new_with_session(
    provider.fork(),
    registry.clone(),
    child_session,
    allowed,
);
agent.set_system_prompt(workflow_prompt);
agent.set_max_turns(max_turns);
let result = agent.run_once_capture(&subtask_prompt).await;

code-review

Execution flow:

1. Identify files to review (from user input or recent changes)
2. Spawn reviewer agent with review-focused system prompt
3. Agent reads files, analyzes, generates report
4. Return structured review with findings

security-review

Execution flow:

1. Identify scope (files, modules)
2. Spawn security agent with OWASP-focused prompt
3. Agent scans for: injection, auth issues, secrets, XSS, CSRF
4. Return findings ranked by severity

deepsearch

Execution flow:

1. Parse search query from user input
2. Spawn 3 search agents in parallel:
   • Agent 1: Text/regex search (grep-based)
   • Agent 2: Structural search (AST/function-level)
   • Agent 3: Semantic search (concept-level)
3. Merge results, deduplicate by file:line
4. Build context map with related code snippets
5. Return unified search results

Phase 4: Tier 3 — Loop Orchestration Workflows

ultraqa

State machine:

States: Implement → Test → Fix → Check → Done
Transitions:
  Implement → Test (after implementation)
  Test → Fix (if tests fail)
  Fix → Test (after fix)
  Test → Check (if tests pass)
  Check → Done (max iterations reached or all pass)
  Fix → Done (max 5 iterations)

Execution:

1. Turn N: Inject "Implement the following: {user_input}" as system reminder
2. After LLM implements, inject "Run tests and report results"
3. If tests fail, inject "Fix the following failures: {failures}"
4. Track iteration count in ModeState.metadata["qa_iterations"]
5. After 5 iterations or all tests pass, inject completion summary

Hook: on_turn_complete() checks test results, decides next state.

tdd

State machine:

States: WriteTest → RunTest → Implement → RunTest → Refactor → Done
Per behavior:
  Write test → verify it fails (RED)
  Implement → verify it passes (GREEN)
  Refactor → verify tests still pass

Execution:

1. Turn N: Inject "Write a failing test for: {behavior}"
2. After test written, inject "Run the test, verify it fails (RED)"
3. After RED confirmed, inject "Implement minimal code to pass (GREEN)"
4. After GREEN confirmed, inject "Refactor while keeping tests green"
5. Move to next behavior or complete

ralplan

State machine:

States: Plan → Review → Revise → Approve → Execute
Transitions:
  Plan → Review (after plan generated)
  Review → Revise (if issues found)
  Revise → Review (after revision)
  Review → Approve (if plan looks good)
  Approve → Execute (after user approval)

Execution:

1. Turn N: Inject "Generate a plan for: {user_input}"
2. After plan, inject "Self-review: identify risks, gaps, assumptions"
3. After review, inject "Revise plan addressing: {issues}"
4. After revision, ask user for approval
5. After approval, inject "Execute the approved plan"

Phase 5: Tier 4 — Interactive Workflows

deep-interview

Execution:

1. Turn N: Analyze user input for ambiguity
2. Score ambiguity 1-10
3. If score >= 3, inject clarifying questions (max 3 per round)
4. Track answers in ModeState.metadata["interview_answers"]
5. Re-score ambiguity after each round
6. When score < 3, summarize requirements and proceed

Special: Uses WorkflowAction::AskUser() to pause and wait for answers.

Phase 6: Tier 5 — State Management Workflows

ultragoal

Execution:

1. Parse goal from user input
2. Create goal state in .jcode/state/goals.toml:

   [goal]
   description = "..."
   token_budget = 100000
   tokens_used = 0
   progress = 0.0
   status = "active"

3. Each turn: inject progress report + next steps
4. Track token usage across turns
5. When budget exhausted or goal achieved, report completion

Phase 7: Tier 6 — System Action Workflows

cancel

Execution:

1. Clear all active modes in .jcode/state/modes.toml
2. Clear goal state in .jcode/state/goals.toml
3. Inject "All modes cancelled" as system reminder
4. Publish BusEvent to notify TUI

Integration Points

A. Enhanced WorkflowHandler trait

• File: crates/jcode-keywords/src/workflow/mod.rs
• Add execute() and on_turn_complete() methods
• Add WorkflowContext and WorkflowAction types

B. Workflow executor in turn loop

• File: crates/jcode-app-core/src/agent/turn_loops.rs
• After build_system_prompt_split(), check for active workflows
• Call workflow_handler.execute(ctx) → handle WorkflowAction
• For SpawnAgent: create sub-agent, run, inject result
• For AskUser: inject question, break turn, resume next turn
• For InjectReminder: add to dynamic_part

C. TUI keyword wiring

• File: crates/jcode-tui/src/tui/app/turn_memory.rs
• Wire keyword detection (same as agent path)
• Add visual feedback for workflow execution (spinner, progress)

D. Workflow state persistence

• File: crates/jcode-keywords/src/state.rs
• Extend ActiveMode with metadata: HashMap<String, String>
• Store iteration counts, ambiguity scores, goal progress

E. Sub-agent spawning utility

• File: crates/jcode-keywords/src/workflow/spawn.rs (new)
• Helper function to spawn sub-agents using SubagentTool pattern
• Handles provider forking, session creation, tool filtering

Files to Create/Modify

New files

File	Lines	Purpose
crates/jcode-keywords/src/workflow/spawn.rs	~200	Sub-agent spawning utility
crates/jcode-keywords/src/workflow/executor.rs	~300	Workflow execution engine

Modified files

File	Change
crates/jcode-keywords/src/workflow/mod.rs	Enhanced trait + WorkflowContext + WorkflowAction
crates/jcode-keywords/src/workflow/ultrawork.rs	Full execution logic with sub-agent spawning
crates/jcode-keywords/src/workflow/ultraqa.rs	Loop state machine
crates/jcode-keywords/src/workflow/tdd.rs	Red-green-refactor cycle
crates/jcode-keywords/src/workflow/ralplan.rs	Plan-review-revise-approve flow
crates/jcode-keywords/src/workflow/deep_interview.rs	Interactive Q&A with ambiguity scoring
crates/jcode-keywords/src/workflow/code_review.rs	Sub-agent spawn + analysis
crates/jcode-keywords/src/workflow/security_review.rs	Sub-agent spawn + OWASP scan
crates/jcode-keywords/src/workflow/deepsearch.rs	Parallel search agents
crates/jcode-keywords/src/workflow/ultragoal.rs	Goal state persistence
crates/jcode-keywords/src/workflow/cancel.rs	State clearing + task cancellation
crates/jcode-keywords/src/state.rs	Add metadata field to ActiveMode
crates/jcode-app-core/src/agent/turn_loops.rs	Workflow execution hook
crates/jcode-app-core/src/agent/prompting.rs	Pass WorkflowContext
crates/jcode-tui/src/tui/app/turn_memory.rs	Wire keyword detection

Implementation Order

1. Phase 1: WorkflowHandler trait enhancement (~300 lines)
2. Phase 2: Tier 1 prompt-only workflows (~400 lines)
3. Phase 3: Sub-agent spawn utility + Tier 2 workflows (~800 lines)
4. Phase 4: Loop orchestration + Tier 3 workflows (~600 lines)
5. Phase 5: Interactive + Tier 4 workflows (~300 lines)
6. Phase 6: State management + Tier 5 workflows (~200 lines)
7. Phase 7: Cancel + integration testing (~200 lines)

Total: ~2,800 lines new/modified

Risk Mitigation

1. Sub-agent failures: Max 3 retries, graceful degradation to prompt-only mode
2. Infinite loops: Hard iteration limits (5 for QA, 3 for interview rounds)
3. State corruption: Atomic TOML writes, backup before modification
4. Performance: Sub-agents run in parallel where possible, timeout after 5 minutes
5. User experience: Clear progress indicators, cancel support at any point