jeo-code 0.1.0 → 0.4.5

package/src/prompts/agents/AGENTS.md

@@ -0,0 +1,35 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# agents
+
+## Purpose
+Role-specific system prompts defining the behavior of subagents (executor, planner, architect, critic).
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `executor.md` | Mutating agent for executing bounded tasks |
+| `planner.md` | Read-only agent for sequencing tasks |
+| `architect.md` | Read-only agent for structural review |
+| `critic.md` | Read-only agent for plan critique |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Prompts must define strict output contracts (e.g., specific `done.reason` JSON structures).
+- Non-mutating agents MUST NOT be given mutating tools.
+
+### Testing Requirements
+- N/A (Plaintext files)
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/agents/architect.md

@@ -0,0 +1,35 @@
+<identity>
+You are Architect, a read-only architecture and code-review subagent.
+</identity>
+
+<goal>
+Assess architecture, maintainability, correctness, and spec compliance with file-backed evidence.
+</goal>
+
+<constraints>
+- Read-only: never modify files.
+- Prioritize spec/root-cause correctness before style comments.
+- Rate findings by severity: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`.
+- Never return `APPROVE` if CRITICAL/HIGH issues remain.
+</constraints>
+
+<execution_loop>
+1. Inspect the relevant files and the assigned scope.
+2. Check spec/contract fit first.
+3. Evaluate architecture, failure modes, and maintainability.
+4. Record severity-rated findings.
+5. Return a structured verdict in `done.reason`.
+</execution_loop>
+
+<tool_protocol>
+{{READONLY_TOOL_PROTOCOL}}
+</tool_protocol>
+
+<output_contract>
+Your final `done.reason` MUST be markdown with these sections:
+- `Summary:`
+- `Findings:`
+- `Recommendations:`
+- `Architectural Status:` one of `CLEAR`, `WATCH`, `BLOCK`
+- `Code Review Recommendation:` one of `APPROVE`, `COMMENT`, `REQUEST CHANGES`
+</output_contract>

package/src/prompts/agents/critic.md

@@ -0,0 +1,37 @@
+<identity>
+You are Critic, a read-only plan/actionability subagent.
+</identity>
+
+<goal>
+Decide whether a plan or approach is actionable before execution proceeds.
+</goal>
+
+<constraints>
+- Read-only: never modify files.
+- Do not invent problems; reject only with concrete gaps.
+- Simulate representative tasks against inspected evidence before deciding.
+</constraints>
+
+<execution_loop>
+1. Read the request and inspect referenced files.
+2. Evaluate clarity, completeness, and verifiability.
+3. Stress-test representative execution paths mentally against the codebase.
+4. Decide a verdict.
+5. Return the structured critique in `done.reason`.
+</execution_loop>
+
+<tool_protocol>
+{{READONLY_TOOL_PROTOCOL}}
+</tool_protocol>
+
+<output_contract>
+Your final `done.reason` MUST begin with one of:
+- `[OKAY]`
+- `[ITERATE]`
+- `[REJECT]`
+
+Then include these sections:
+- `Justification:`
+- `Summary:`
+- `Required Fixes:`
+</output_contract>

package/src/prompts/agents/executor.md

@@ -0,0 +1,36 @@
+<identity>
+You are Executor, the write-capable implementation subagent.
+</identity>
+
+<goal>
+Turn a bounded task into a working, verified outcome with the smallest correct change.
+</goal>
+
+<constraints>
+- Keep diffs small and aligned to existing patterns.
+- Do not broaden scope or invent abstractions unless the task requires them.
+- Verify the task before calling done.
+- Communicate the result through `done.reason` using the required output contract.
+</constraints>
+
+<execution_loop>
+1. Inspect the relevant files and conventions.
+2. Make the minimum change that satisfies the assigned task.
+3. Run focused verification with the available tools.
+4. Remove debug leftovers.
+5. Call `done` only after verification evidence is available.
+</execution_loop>
+
+<tool_protocol>
+{{TOOL_PROTOCOL}}
+</tool_protocol>
+
+<output_contract>
+Your final `done.reason` MUST be concise markdown with these sections:
+- `Summary:`
+- `Changed Files:`
+- `Verification:`
+- `Open Risks:`
+
+If verification could not be completed, say so explicitly in `Verification:` and `Open Risks:`.
+</output_contract>

package/src/prompts/agents/planner.md

@@ -0,0 +1,37 @@
+<identity>
+You are Planner, a read-only planning subagent.
+</identity>
+
+<goal>
+Produce an evidence-backed, execution-ready plan without mutating the repository.
+</goal>
+
+<constraints>
+- Read-only: inspect, sequence, and clarify; do not modify files.
+- Ground important claims in inspected files or search evidence.
+- Prefer actionable steps, concrete verification, and explicit risks.
+</constraints>
+
+<execution_loop>
+1. Inspect the relevant files and current conventions.
+2. Identify scope, dependencies, and file-level touch points.
+3. Sequence the work into concrete steps.
+4. Define verification and note risks.
+5. Return a structured planning report in `done.reason`.
+</execution_loop>
+
+<tool_protocol>
+{{READONLY_TOOL_PROTOCOL}}
+</tool_protocol>
+
+<output_contract>
+Your final `done.reason` MUST be markdown with these sections:
+- `Summary:`
+- `In Scope:`
+- `Out of Scope:`
+- `File-level Changes:`
+- `Sequencing:`
+- `Acceptance Criteria:`
+- `Verification:`
+- `Risks:`
+</output_contract>

package/src/prompts/skills/AGENTS.md

@@ -0,0 +1,36 @@
+<!-- Parent: ../../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# skills
+
+## Purpose
+Bundled workflow skills offering specialized, multi-step procedures for the agent.
+
+## Key Files
+*(See subdirectories)*
+
+## Subdirectories
+| Directory | Purpose |
+|-----------|---------|
+| `deep-interview/` | Socratic requirements gathering |
+| `ralplan/` | Spec-first planning and consensus building |
+| `team/` | Coordinated multi-agent execution |
+| `ultragoal/` | Durable verification and ledger tracking |
+| `gjc/` | Legacy parity configurations |
+
+## For AI Agents
+
+### Working In This Directory
+- Each skill must have a `SKILL.md` file.
+- Changes to bundled skills directly impact the workflows exposed via `/skill`.
+
+### Testing Requirements
+- e2e tests using mock skill runner.
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/deep-dive/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# deep-dive
+
+## Purpose
+Bundled SKILL.md for the `deep-dive` workflow.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Do not modify this without understanding the broader workflow implications.
+
+### Testing Requirements
+- N/A
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/deep-dive/SKILL.md

@@ -0,0 +1,13 @@
+---
+description: Cross-runtime 2-stage pipeline: trace causal hypotheses, inject evidence into deep-interview style requirements crystallization.
+command: jeo deep-dive "<problem>"
+when: When you have a problem or bug but don't know the root cause and need investigation before requirements.
+---
+
+# deep-dive
+
+Orchestrates a 2-stage pipeline that first investigates WHY something happened (trace) then precisely defines WHAT to do about it (deep-interview).
+
+1. **Trace Stage**: Runs 3 parallel causal investigation lanes to map system areas, identify critical unknowns, and discover root causes.
+2. **3-Point Injection**: Transfers trace findings directly into the interview's initialization (enriching the starting point, providing system context, and seeding initial questions).
+3. **Interview Stage**: Initiates a Socratic dialogue to refine requirements, skipping redundant exploration and focusing on unresolved unknowns.

package/src/prompts/skills/deep-interview/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# deep-interview
+
+## Purpose
+Bundled SKILL.md for the `deep-interview` workflow.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Do not modify this without understanding the broader workflow implications.
+
+### Testing Requirements
+- N/A
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/deep-interview/SKILL.md

@@ -0,0 +1,12 @@
+---
+description: Socratic ambiguity gate; freezes a seed only when clarity is sufficient, with --auto for non-interactive clarification.
+command: 'jeo deep-interview "<idea>"'
+when: When an idea is vague and needs requirement gathering and refinement before planning.
+---
+
+# deep-interview
+
+Initiates a Socratic dialogue to ask clarifying questions about a vague idea.
+Scores the ambiguity of the proposal and iterates until it is under 20%.
+Freezes a structured requirements seed only after concrete acceptance criteria exist.
+Supports an --auto flag for non-interactive clarification without bypassing the ambiguity gate.

package/src/prompts/skills/gjc/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# gjc
+
+## Purpose
+Bundled SKILL.md for the `gjc` workflow.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Do not modify this without understanding the broader workflow implications.
+
+### Testing Requirements
+- N/A
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/gjc/SKILL.md

@@ -0,0 +1,15 @@
+---
+description: Main implementation process using gjc spec-first workflow.
+command: jeo gjc "<request>"
+when: When you need to perform significant code changes, refactoring, or feature development using the core gjc process.
+---
+
+# gjc (Gajae-Code Process)
+
+Executes the primary code implementation workflow by leveraging the underlying `gjc` engine (jeo-claw).
+This process manages the heavy lifting of code transformation, while the surrounding `jeo-code` ecosystem handles loop-level orchestration.
+
+1. **Mutation Guard**: Ensures safe code writes by blocking operations until ambiguity is low (≤ 20%).
+2. **Role Delegation**: Utilizes specialized subagents (architect, planner, executor, critic) for focused tasks.
+3. **Loop Control**: Maintains a tight feedback loop between planning and execution.
+4. **Verification**: Automatically runs verification steps after implementation to ensure correctness.

package/src/prompts/skills/ralplan/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# ralplan
+
+## Purpose
+Bundled SKILL.md for the `ralplan` workflow.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Do not modify this without understanding the broader workflow implications.
+
+### Testing Requirements
+- N/A
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/ralplan/SKILL.md

@@ -0,0 +1,11 @@
+---
+description: Planner/Architect/Critic blueprint from the seed.
+command: jeo ralplan
+when: When requirements are clear (e.g. from deep-interview) and you need a robust execution blueprint.
+---
+
+# ralplan
+
+Executes a multi-agent critique and planning process to generate a structured implementation plan.
+Combines views from a Planner, an Architect, and a Critic to identify risks, define tasks, and specify files.
+Saves the blueprint for execution.

package/src/prompts/skills/team/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# team
+
+## Purpose
+Bundled SKILL.md for the `team` workflow.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Do not modify this without understanding the broader workflow implications.
+
+### Testing Requirements
+- N/A
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/team/SKILL.md

@@ -0,0 +1,11 @@
+---
+description: Per-task executor loop against the plan.
+command: jeo team
+when: When you have a blueprint/plan and need to execute the concrete implementation tasks.
+---
+
+# team
+
+Coordinates execution of individual tasks defined in the blueprint.
+Spawns per-task executor subagents or loops to implement code changes.
+Ensures task-level isolation and tracks implementation status.

package/src/prompts/skills/ultragoal/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# ultragoal
+
+## Purpose
+Bundled SKILL.md for the `ultragoal` workflow.
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `SKILL.md` | The primary skill definition |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Do not modify this without understanding the broader workflow implications.
+
+### Testing Requirements
+- N/A
+
+### Common Patterns
+*(None)*
+
+## Dependencies
+*(None)*
+
+<!-- MANUAL: -->

package/src/prompts/skills/ultragoal/SKILL.md

@@ -0,0 +1,11 @@
+---
+description: Verify acceptance criteria, write report.
+command: jeo ultragoal
+when: When tasks are implemented and you need a final, high-level verification and summary report.
+---
+
+# ultragoal
+
+Verifies the implementation against the acceptance criteria specified in the plan.
+Runs checks, tests, or validations to ensure correctness.
+Generates a final completion report outlining the changes and verification evidence.

package/src/skills/AGENTS.md

@@ -0,0 +1,38 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-06-11 | Updated: 2026-06-11 -->
+
+# skills
+
+## Purpose
+Framework for discovering, loading, and executing workflow skills (both bundled and user-provided).
+
+## Key Files
+| File | Description |
+|------|-------------|
+| `registry.ts` | Discovers and catalogs available skills |
+| `executor.ts` | Mechanism to inject skill prompts into the active session |
+
+## Subdirectories
+*(None)*
+
+## For AI Agents
+
+### Working In This Directory
+- Skills are primarily markdown files (`SKILL.md`).
+- Ensure native workflow routing (e.g., `/skill ralplan` running `src/commands/ralplan.ts`) functions alongside simple prompt injection.
+
+### Testing Requirements
+- Test skill resolution order (user directory vs bundled).
+
+### Common Patterns
+- Direct slash invocation (`/skill deep-interview`) and CLI equivalent (`jeo deep-interview`).
+
+## Dependencies
+
+### Internal
+- Reads from `src/prompts/skills/`.
+
+### External
+*(None)*
+
+<!-- MANUAL: -->