Skip to content

Refactor command workflows and add inline variants #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dbpolito merged 4 commits into from
Jul 17, 2026
Merged

Refactor command workflows and add inline variants #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b0f5f2e
refactor: simplify command workflows
dbpolito Jul 16, 2026
a9e3f31
feat: add inline completion command variants
dbpolito Jul 16, 2026
901e537
refactor: simplify command workflow composition
dbpolito Jul 16, 2026
9fe224f
fix: require inspection of deferred diffs
dbpolito Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 7 additions & 40 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,17 +61,14 @@ packages/opencode/.opencode/ # Generated OpenCode output for review
- Use angle-bracket placeholders consistently for derived values and stored context, such as `<arguments>`, `<base>`, `<additional-context>`, `<pr-url>`, and define each placeholder before it is referenced later in the command
- When referring to placeholders literally in prose, always wrap them in backticks, such as `<arguments>` or `<pr-url>`; keep output examples plain when the placeholder represents substituted user-facing text
- If arguments can mean different things, explicitly disambiguate them in `### Interpret Arguments` and store each interpretation in a separate placeholder
- For navigator-style commands, separate context loading, blocker checks, delegated execution, and final reporting into distinct workflow subsections so the control flow is easy to follow
- Prefer explicit subsection names like `### Load ... Context`, `### Check Blockers`, `### Delegate ...`, and `### Mark Complete And Loop` when the command coordinates multiple phases or subagents
- For multi-step commands, separate context loading, blocker checks, execution, and final reporting into distinct workflow subsections so the control flow is easy to follow
- Prefer explicit subsection names like `### Load ... Context`, `### Check Blockers`, and `### Mark Complete And Loop` when a command coordinates multiple phases
- Treat loader tools and provided attachments as the source of truth for orchestration inputs; avoid extra exploratory commands when an existing tool result already answers the question
- Before dispatching a same-session command step, say what delegated result should be stored and whether the workflow must stop, pause, or continue based on that result
- Use literal `<delegate>` tags when the workflow must delegate exact text through `command_expansion`; `agent` and `command` are required, and the block body is the exact rendered body to send for that command
- Do not use `<task>` blocks in command docs; author navigator delegation with `<delegate>` blocks only
- Do not restate `command_expansion` or `task` mechanics inside command docs; navigator owns that execution flow
- Reuse component phases within a command so state can be carried forward without repeated loader calls
- When a command can pause for approval or loop over repeated work, describe the resume condition and the exact cases that must STOP without mutating state
- Use `## Additional Context` for instructions about how optional guidance, related tickets, focus areas, or other stored context should influence analysis and response formatting
- Use `### Output` as the final workflow step to define the exact user-facing response shape, including placeholders for generated values
- Make success, blocked, no-op, waiting, and resume-required outcomes explicit in `### Output` or the surrounding workflow so navigator-led flows report deterministic end states
- Make success, blocked, no-op, waiting, and resume-required outcomes explicit in `### Output` or the surrounding workflow so multi-step flows report deterministic end states
- For terminal command outcomes, prefer an explicit final line inside the output block: `No additional steps are required.`
- Omit that final line for outputs that intentionally wait for approval, pause for resume, loop to the next task, or otherwise continue beyond the current checkpoint
- For one-off commands that do not orchestrate follow-up work, make every success, blocked, or no-op output explicitly terminal with that final line
Expand Down Expand Up @@ -106,47 +103,17 @@ $ARGUMENTS
- Load the required file, ticket, or PR context
- STOP if the source of truth cannot be loaded

### Delegate Planning
### Execute Workflow

<delegate agent="planner" command="ticket/plan">

Task: <task>
Task context: <task-context>
Additional context: <additional-context>
</delegate>

- Store the delegated result as `<plan>`
- STOP if planning is blocked or unusable

### Delegate Implementation

<delegate agent="worker" command="dev">

Plan: <plan>
Constraints: <additional-context>
</delegate>

- Store the delegated result as `<implementation-result>`
- STOP if implementation is blocked or incomplete
- Run reusable component phases inline and preserve their named results
- STOP if a required phase is blocked or incomplete

### Output

- Define the exact success, blocked, and no-op response shapes
- For terminal outcomes, end the output block with `No additional steps are required.` Omit that line when the command is intentionally waiting, looping, or continuing.
```

Example delegation rule:

```text
Before delegation, write the exact `<delegate ...>...</delegate>` block, say what delegated result should be stored, and whether the workflow should continue or STOP based on that result.
```

Example literal session command rule:

```text
Before literal command forwarding, write the exact `<delegate ...>...</delegate>` block, then let navigator expand and execute it, and say what delegated result should be stored and whether the workflow should continue or STOP based on that result.
```

## Component Authoring

- Store reusable command fragments in `packages/core/components/`
Expand Down
6 changes: 3 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ Kompass keeps AI coding agents on course with token-efficient, composable workfl

## Bundled Surface

- Commands cover direct work (`/ask`, `/commit`, `/merge`, `/skill/create`, `/skill/optimize`), orchestration (`/dev`, `/ship`, `/todo`, `/loop/pr/fix`), ticket planning/sync, and PR review/shipping flows.
- Agents are intentionally narrow: `worker` is generic, `planner` is no-edit planning, `navigator` owns multi-step orchestration, and `reviewer` is a no-edit review specialist.
- Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `command_expansion` (resolve a slash command and return the expanded prompt for immediate delegation), `pr_load`, `pr_sync`, `ticket_load`, `ticket_sync`.
- Commands cover direct work (`/ask`, `/commit`, `/merge`, `/skill/create`, `/skill/optimize`), orchestration (`/dev`, `/ship`, `/todo`, `/pr/fix/loop`), ticket planning/sync, and PR review/shipping flows. `/branch/inline`, `/commit/inline`, `/commit-and-push/inline`, `/pr/create/inline`, and `/ship/inline` reuse the invoking session instead of starting a subtask.
- Agents are intentionally narrow: `worker` handles implementation and multi-step workflows, `planner` is no-edit planning, and `reviewer` is a no-edit review specialist.
- Structured tools keep workflows grounded in repo and GitHub state: `changes_load`, `pr_load`, `pr_load_review`, `pr_sync`, `ticket_load`, `ticket_sync`.
- Reusable command-template components live in `packages/core/components/` and are documented in the components reference.

## Prerequisites
Expand Down
17 changes: 13 additions & 4 deletions kompass.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,19 +13,24 @@
"commands": {
"ask": { "enabled": true },
"branch": { "enabled": true },
"branch/inline": { "enabled": true },
"commit": { "enabled": true },
"commit/inline": { "enabled": true },
"commit-and-push": { "enabled": true },
"commit-and-push/inline": { "enabled": true },
"dev": { "enabled": true },
"learn": { "enabled": true },
"loop/pr/fix": { "enabled": true },
"merge": { "enabled": true },
"pr/create": { "enabled": true },
"pr/create/inline": { "enabled": true },
"pr/fix": { "enabled": true },
"pr/fix/loop": { "enabled": true },
"pr/review": { "enabled": true },
"review": { "enabled": true },
"skill/create": { "enabled": true },
"skill/optimize": { "enabled": true },
"ship": { "enabled": true },
"ship/inline": { "enabled": true },
"rmslop": { "enabled": true },
"todo": { "enabled": true },
"ticket/ask": { "enabled": true },
Expand All @@ -37,29 +42,33 @@

"agents": {
"worker": { "enabled": true },
"navigator": { "enabled": true },
"planner": { "enabled": true },
"reviewer": { "enabled": true },
},

"tools": {
"changes_load": { "enabled": true },
"command_expansion": { "enabled": true },
"pr_load": { "enabled": true },
"pr_load_review": { "enabled": true },
"pr_sync": { "enabled": true },
"ticket_load": { "enabled": true },
"ticket_sync": { "enabled": true },
},

"components": {
"change-summary": { "enabled": true },
"branch": { "enabled": true },
"changes-summary": { "enabled": true },
"commit": { "enabled": true },
"dev-flow": { "enabled": true },
"load-pr": { "enabled": true },
"load-ticket": { "enabled": true },
"pr-create": { "enabled": true },
"pr-branch-update": { "enabled": true },
"pr-fix": { "enabled": true },
"push": { "enabled": true },
"skill-authoring": { "enabled": true },
"summarize-changes": { "enabled": true },
"ticket-planning": { "enabled": true },
},

"defaults": {
Expand Down
67 changes: 52 additions & 15 deletions kompass.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,19 +38,25 @@
"branch": {
"$ref": "#/$defs/commandConfig"
},
"branch/inline": {
"$ref": "#/$defs/commandConfig"
},
"commit": {
"$ref": "#/$defs/commandConfig"
},
"commit/inline": {
"$ref": "#/$defs/commandConfig"
},
"commit-and-push": {
"$ref": "#/$defs/commandConfig"
},
"dev": {
"commit-and-push/inline": {
"$ref": "#/$defs/commandConfig"
},
"learn": {
"dev": {
"$ref": "#/$defs/commandConfig"
},
"loop/pr/fix": {
"learn": {
"$ref": "#/$defs/commandConfig"
},
"merge": {
Expand All @@ -59,9 +65,15 @@
"pr/create": {
"$ref": "#/$defs/commandConfig"
},
"pr/create/inline": {
"$ref": "#/$defs/commandConfig"
},
"pr/fix": {
"$ref": "#/$defs/commandConfig"
},
"pr/fix/loop": {
"$ref": "#/$defs/commandConfig"
},
"pr/review": {
"$ref": "#/$defs/commandConfig"
},
Expand All @@ -77,6 +89,9 @@
"ship": {
"$ref": "#/$defs/commandConfig"
},
"ship/inline": {
"$ref": "#/$defs/commandConfig"
},
"rmslop": {
"$ref": "#/$defs/commandConfig"
},
Expand Down Expand Up @@ -105,19 +120,24 @@
"enum": [
"ask",
"branch",
"branch/inline",
"commit",
"commit/inline",
"commit-and-push",
"commit-and-push/inline",
"dev",
"learn",
"loop/pr/fix",
"merge",
"pr/create",
"pr/create/inline",
"pr/fix",
"pr/fix/loop",
"pr/review",
"review",
"skill/create",
"skill/optimize",
"ship",
"ship/inline",
"rmslop",
"todo",
"ticket/ask",
Expand All @@ -136,19 +156,24 @@
"enum": [
"ask",
"branch",
"branch/inline",
"commit",
"commit/inline",
"commit-and-push",
"commit-and-push/inline",
"dev",
"learn",
"loop/pr/fix",
"merge",
"pr/create",
"pr/create/inline",
"pr/fix",
"pr/fix/loop",
"pr/review",
"review",
"skill/create",
"skill/optimize",
"ship",
"ship/inline",
"rmslop",
"todo",
"ticket/ask",
Expand All @@ -172,9 +197,6 @@
"worker": {
"$ref": "#/$defs/agentConfig"
},
"navigator": {
"$ref": "#/$defs/agentConfig"
},
"planner": {
"$ref": "#/$defs/agentConfig"
},
Expand All @@ -185,7 +207,7 @@
"type": "array",
"items": {
"type": "string",
"enum": ["worker", "navigator", "planner", "reviewer"]
"enum": ["worker", "planner", "reviewer"]
},
"uniqueItems": true,
"deprecated": true
Expand All @@ -199,10 +221,10 @@
"changes_load": {
"$ref": "#/$defs/toolConfig"
},
"command_expansion": {
"pr_load": {
"$ref": "#/$defs/toolConfig"
},
"pr_load": {
"pr_load_review": {
"$ref": "#/$defs/toolConfig"
},
"pr_sync": {
Expand All @@ -223,6 +245,9 @@
"change-summary": {
"$ref": "#/$defs/componentConfig"
},
"branch": {
"$ref": "#/$defs/componentConfig"
},
"changes-summary": {
"$ref": "#/$defs/componentConfig"
},
Expand All @@ -238,25 +263,37 @@
"load-ticket": {
"$ref": "#/$defs/componentConfig"
},
"pr-create": {
"$ref": "#/$defs/componentConfig"
},
"pr-branch-update": {
"$ref": "#/$defs/componentConfig"
},
"pr-fix": {
"$ref": "#/$defs/componentConfig"
},
"push": {
"$ref": "#/$defs/componentConfig"
},
"skill-authoring": {
"$ref": "#/$defs/componentConfig"
},
"summarize-changes": {
"ticket-planning": {
"$ref": "#/$defs/componentConfig"
},
"enabled": {
"type": "array",
"items": {
"type": "string",
"enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"]
"enum": ["branch", "change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "pr-create", "pr-branch-update", "pr-fix", "push", "skill-authoring", "ticket-planning"]
},
"uniqueItems": true,
"deprecated": true
},
"paths": {
"type": "object",
"propertyNames": {
"enum": ["change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "skill-authoring", "summarize-changes"]
"enum": ["branch", "change-summary", "changes-summary", "commit", "dev-flow", "load-pr", "load-ticket", "pr-create", "pr-branch-update", "pr-fix", "push", "skill-authoring", "ticket-planning"]
},
"additionalProperties": {
"type": "string"
Expand Down Expand Up @@ -391,8 +428,8 @@
"type": "string",
"enum": [
"changes_load",
"command_expansion",
"pr_load",
"pr_load_review",
"pr_sync",
"ticket_sync",
"ticket_load"
Expand Down
1 change: 0 additions & 1 deletion packages/core/agents/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ export interface ResolvedAgentDefinition
export function getAgentDefinitions(config: ReturnType<typeof mergeWithDefaults>): Record<string, AgentDefinition> {
return {
worker: config.agents.worker,
navigator: config.agents.navigator,
reviewer: config.agents.reviewer,
planner: config.agents.planner,
};
Expand Down
31 changes: 0 additions & 31 deletions packages/core/agents/navigator.md
View file
Open in desktop

This file was deleted.

1 change: 1 addition & 0 deletions packages/core/agents/reviewer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Before reviewing, always check repository guidance:
- In CI or shallow clones, pass explicit base and head refs
- For branch comparisons, treat the returned commit list as the authoritative scope: review the commits ahead of base and use file diffs only as supporting context
- Scan the summary first to understand scope, file states, and risk clusters
- If the result reports deferred diffs, inspect them directly one file at a time using the returned comparison and changed paths
- Never switch branches, create local review branches, or otherwise mutate `HEAD`; if a loader fails, prefer reporting the blocker over changing checkout state

2. **Read Code**: Read every changed file individually before finalizing
Expand Down
Loading
Loading