Skip to content

Commit 86f23d8

Browse files
authored
Merge pull request #81 from dmoliveira/my_opencode-e14-execution-bridge
Implement E14-T2 start-work execution backend
2 parents abab754 + 133f04a commit 86f23d8

File tree

8 files changed

+661
-6
lines changed

8 files changed

+661
-6
lines changed

CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,8 @@ All notable changes to this project are documented in this file.
4444
- Added `/browser`, `/browser-status`, `/browser-profile`, and `/browser-doctor-json` aliases in `opencode.json`.
4545
- Added browser profile selection support to `scripts/install_wizard.py` via `--browser-profile <playwright|agent-browser>`.
4646
- Added `instructions/plan_artifact_contract.md` defining `/start-work` plan metadata/checklist format, validation rules, step transitions, and deviation capture requirements.
47+
- Added `scripts/start_work_command.py` with `/start-work <plan>` execution, persisted checkpoint status, and deviation reporting (`status`, `deviations`).
48+
- Added `/start-work`, `/start-work-status`, and `/start-work-deviations` aliases in `opencode.json`.
4749

4850
### Changes
4951
- Documented extension evaluation outcomes and when each tool is the better fit.
@@ -85,6 +87,7 @@ All notable changes to this project are documented in this file.
8587
- Expanded install and selftest coverage for browser provider profile switching and missing dependency guidance.
8688
- Expanded README wizard/browser guidance with provider trade-offs, stable-first defaults, and `/browser` usage examples.
8789
- Expanded browser verification coverage to assert provider reset readiness and added install smoke checks that run browser status/doctor after switching across providers.
90+
- Expanded install/selftest coverage for `/start-work` plan validation, execution state persistence, and deviation diagnostics.
8891

8992
## v0.2.0 - 2026-02-12
9093

IMPLEMENTATION_ROADMAP.md

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ Use this map to avoid overlapping implementations.
5050
| E11 | Context-Window Resilience Toolkit | done | High | E4 | bd-2tj, bd-n9y, bd-2t0, bd-18e | Improve long-session stability and recovery |
5151
| E12 | Provider/Model Fallback Visibility | done | Medium | E5 | bd-1jq, bd-298, bd-194, bd-2gq | Explain why model routing decisions happen |
5252
| E13 | Browser Automation Profile Switching | done | Medium | E1 | bd-3rs, bd-2qy, bd-f6g, bd-393 | Toggle Playwright/agent-browser with checks |
53-
| E14 | Plan-to-Execution Bridge Command | in_progress | Medium | E2, E3 | bd-1z6 | Execute validated plans with progress tracking |
53+
| E14 | Plan-to-Execution Bridge Command | in_progress | Medium | E2, E3 | bd-1z6, bd-2te | Execute validated plans with progress tracking |
5454
| E15 | Todo Enforcer and Plan Compliance | planned | High | E14 | TBD | Keep execution aligned with approved checklists |
5555
| E16 | Comment and Output Quality Checker Loop | merged | Medium | E23 | TBD | Merged into E23 (PR Review Copilot) |
5656
| E17 | Auto-Resume and Recovery Loop | planned | High | E11, E14 | TBD | Resume interrupted work from checkpoints safely |
@@ -573,10 +573,11 @@ Every command-oriented epic must ship all of the following:
573573
- [x] Subtask 14.1.2: Define validation rules before execution starts
574574
- [x] Subtask 14.1.3: Define step state transitions and completion semantics
575575
- [x] Notes: Added `instructions/plan_artifact_contract.md` covering artifact schema, deterministic validation failures, transition rules, and deviation capture requirements for `/start-work`.
576-
- [ ] Task 14.2: Implement execution bridge backend
577-
- [ ] Subtask 14.2.1: Add `/start-work <plan>` command implementation
578-
- [ ] Subtask 14.2.2: Execute steps sequentially with checkpoint updates
579-
- [ ] Subtask 14.2.3: Capture and report deviations from original plan
576+
- [x] Task 14.2: Implement execution bridge backend
577+
- [x] Subtask 14.2.1: Add `/start-work <plan>` command implementation
578+
- [x] Subtask 14.2.2: Execute steps sequentially with checkpoint updates
579+
- [x] Subtask 14.2.3: Capture and report deviations from original plan
580+
- [x] Notes: Added `scripts/start_work_command.py` with plan parsing + validation, sequential checkpoint transitions, persisted execution status, and deviation reporting; wired aliases and smoke/selftest coverage.
580581
- [ ] Task 14.3: Integrations and observability
581582
- [ ] Subtask 14.3.1: Integrate with background subsystem where safe
582583
- [ ] Subtask 14.3.2: Integrate with digest summaries for end-of-run recap

Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ install-test: ## Run installer smoke test in temp HOME
4848
HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/stack_profile_command.py" apply focus; \
4949
HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/stack_profile_command.py" status; \
5050
if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" ]; then HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" profile agent-browser; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" doctor --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" profile playwright; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/browser_command.py" doctor --json; fi; \
51+
if [ -f "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" ]; then PLAN_FILE="$$TMP_HOME/.config/opencode/my_opencode/.install-test-plan.md"; python3 -c "from pathlib import Path; Path('$$PLAN_FILE').write_text('---\nid: install-test-plan\ntitle: Install Test Plan\nowner: install-test\ncreated_at: 2026-02-13T00:00:00Z\nversion: 1\n---\n\n# Plan\n\n- [ ] 1. Validate command availability\n- [ ] 2. Validate status persistence\n', encoding='utf-8')"; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" "$$PLAN_FILE" --deviation "install smoke" --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" status --json; HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/start_work_command.py" deviations --json; fi; \
5152
HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/nvim_integration_command.py" install minimal --link-init; \
5253
HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/nvim_integration_command.py" status; \
5354
HOME="$$TMP_HOME" python3 "$$TMP_HOME/.config/opencode/my_opencode/scripts/devtools_command.py" status; \

README.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@ git clone https://github.com/dmoliveira/my_opencode.git ~/.config/opencode/my_op
231231
ln -sfn ~/.config/opencode/my_opencode/opencode.json ~/.config/opencode/opencode.json
232232
chmod +x ~/.config/opencode/my_opencode/install.sh ~/.config/opencode/my_opencode/scripts/mcp_command.py
233233
chmod +x ~/.config/opencode/my_opencode/scripts/plugin_command.py
234-
chmod +x ~/.config/opencode/my_opencode/scripts/notify_command.py ~/.config/opencode/my_opencode/scripts/session_digest.py ~/.config/opencode/my_opencode/scripts/opencode_session.sh ~/.config/opencode/my_opencode/scripts/telemetry_command.py ~/.config/opencode/my_opencode/scripts/post_session_command.py ~/.config/opencode/my_opencode/scripts/policy_command.py ~/.config/opencode/my_opencode/scripts/doctor_command.py ~/.config/opencode/my_opencode/scripts/config_command.py ~/.config/opencode/my_opencode/scripts/stack_profile_command.py ~/.config/opencode/my_opencode/scripts/browser_command.py ~/.config/opencode/my_opencode/scripts/install_wizard.py ~/.config/opencode/my_opencode/scripts/nvim_integration_command.py
234+
chmod +x ~/.config/opencode/my_opencode/scripts/notify_command.py ~/.config/opencode/my_opencode/scripts/session_digest.py ~/.config/opencode/my_opencode/scripts/opencode_session.sh ~/.config/opencode/my_opencode/scripts/telemetry_command.py ~/.config/opencode/my_opencode/scripts/post_session_command.py ~/.config/opencode/my_opencode/scripts/policy_command.py ~/.config/opencode/my_opencode/scripts/doctor_command.py ~/.config/opencode/my_opencode/scripts/config_command.py ~/.config/opencode/my_opencode/scripts/stack_profile_command.py ~/.config/opencode/my_opencode/scripts/browser_command.py ~/.config/opencode/my_opencode/scripts/start_work_command.py ~/.config/opencode/my_opencode/scripts/install_wizard.py ~/.config/opencode/my_opencode/scripts/nvim_integration_command.py
235235
chmod +x ~/.config/opencode/my_opencode/scripts/devtools_command.py
236236
chmod +x ~/.config/opencode/my_opencode/scripts/background_task_manager.py
237237
```
@@ -584,10 +584,18 @@ Recommended workflow:
584584
Epic 14 Task 14.1 defines the baseline plan format and execution-state rules for the upcoming `/start-work <plan>` command:
585585

586586
- contract spec: `instructions/plan_artifact_contract.md`
587+
- backend command: `scripts/start_work_command.py`
587588
- format scope: markdown checklist + YAML metadata frontmatter
588589
- validation scope: deterministic preflight failures with line-level remediation hints
589590
- state model scope: `pending/in_progress/completed/failed/skipped` with strict transition semantics
590591

592+
Use:
593+
```text
594+
/start-work path/to/plan.md --json
595+
/start-work status --json
596+
/start-work deviations --json
597+
```
598+
591599
## Context resilience policy
592600

593601
Epic 11 Task 11.1 defines the baseline policy schema for context-window resilience:
@@ -934,6 +942,7 @@ For your LangGraph setup, default endpoint target is `http://localhost:3000/open
934942
- `scripts/config_command.py` - backend script for `/config`
935943
- `scripts/stack_profile_command.py` - backend script for `/stack`
936944
- `scripts/browser_command.py` - backend script for `/browser`
945+
- `scripts/start_work_command.py` - backend script for `/start-work`
937946
- `scripts/install_wizard.py` - interactive install/reconfigure wizard
938947
- `scripts/nvim_integration_command.py` - backend script for `/nvim`
939948
- `scripts/devtools_command.py` - backend script for `/devtools`

install.sh

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,9 @@ chmod +x "$INSTALL_DIR/scripts/mcp_command.py" "$INSTALL_DIR/scripts/plugin_comm
7272
if [ -f "$INSTALL_DIR/scripts/browser_command.py" ]; then
7373
chmod +x "$INSTALL_DIR/scripts/browser_command.py"
7474
fi
75+
if [ -f "$INSTALL_DIR/scripts/start_work_command.py" ]; then
76+
chmod +x "$INSTALL_DIR/scripts/start_work_command.py"
77+
fi
7578
ln -sfn "$INSTALL_DIR/opencode.json" "$CONFIG_PATH"
7679

7780
if [ "$RUN_WIZARD" = true ]; then
@@ -107,6 +110,13 @@ if [ "$SKIP_SELF_CHECK" = false ]; then
107110
python3 "$INSTALL_DIR/scripts/stack_profile_command.py" status
108111
python3 "$INSTALL_DIR/scripts/browser_command.py" status
109112
python3 "$INSTALL_DIR/scripts/browser_command.py" doctor --json
113+
if [ -f "$INSTALL_DIR/scripts/start_work_command.py" ]; then
114+
SELF_CHECK_PLAN="$HOME/.config/opencode/my_opencode/.install-selfcheck-plan.md"
115+
python3 -c "from pathlib import Path; Path('$SELF_CHECK_PLAN').write_text('---\nid: install-selfcheck-plan\ntitle: Install Selfcheck Plan\nowner: installer\ncreated_at: 2026-02-13T00:00:00Z\nversion: 1\n---\n\n# Plan\n\n- [ ] 1. Confirm command wiring\n- [ ] 2. Confirm checkpoint persistence\n', encoding='utf-8')"
116+
python3 "$INSTALL_DIR/scripts/start_work_command.py" "$SELF_CHECK_PLAN" --deviation "install self-check" --json
117+
python3 "$INSTALL_DIR/scripts/start_work_command.py" status --json
118+
python3 "$INSTALL_DIR/scripts/start_work_command.py" deviations --json
119+
fi
110120
python3 "$INSTALL_DIR/scripts/nvim_integration_command.py" status
111121
python3 "$INSTALL_DIR/scripts/devtools_command.py" status
112122
python3 "$INSTALL_DIR/scripts/doctor_command.py" run || true
@@ -165,6 +175,9 @@ printf " /stack apply focus\n"
165175
printf " /browser status\n"
166176
printf " /browser profile agent-browser\n"
167177
printf " /browser doctor --json\n"
178+
printf " /start-work ~/.config/opencode/my_opencode/plan.md --json\n"
179+
printf " /start-work status --json\n"
180+
printf " /start-work deviations --json\n"
168181
printf " /nvim status\n"
169182
printf " /devtools status\n"
170183
printf " /devtools install all\n"

opencode.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,18 @@
270270
"description": "Run browser provider diagnostics in JSON",
271271
"template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/browser_command.py\" doctor --json`\nShow only the command output."
272272
},
273+
"start-work": {
274+
"description": "Execute an approved plan artifact and persist checkpoints",
275+
"template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/start_work_command.py\" $ARGUMENTS`\nShow only the command output."
276+
},
277+
"start-work-status": {
278+
"description": "Show latest plan execution status",
279+
"template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/start_work_command.py\" status --json`\nShow only the command output."
280+
},
281+
"start-work-deviations": {
282+
"description": "Show captured plan execution deviations",
283+
"template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/start_work_command.py\" deviations --json`\nShow only the command output."
284+
},
273285
"nvim": {
274286
"description": "Manage Neovim OpenCode integration (status|doctor|snippet|install|uninstall)",
275287
"template": "!`python3 \"$HOME/.config/opencode/my_opencode/scripts/nvim_integration_command.py\" $ARGUMENTS`\nShow only the command output."

scripts/selftest.py

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@
5858
RULES_SCRIPT = REPO_ROOT / "scripts" / "rules_command.py"
5959
RESILIENCE_SCRIPT = REPO_ROOT / "scripts" / "context_resilience_command.py"
6060
BROWSER_SCRIPT = REPO_ROOT / "scripts" / "browser_command.py"
61+
START_WORK_SCRIPT = REPO_ROOT / "scripts" / "start_work_command.py"
6162
BASE_CONFIG = REPO_ROOT / "opencode.json"
6263

6364

@@ -1649,6 +1650,122 @@ def run_bg(*args: str) -> subprocess.CompletedProcess[str]:
16491650
"browser doctor should report ready selected provider after reset",
16501651
)
16511652

1653+
plan_path = tmp / "plan_execution_selftest.md"
1654+
plan_path.write_text(
1655+
"""---
1656+
id: selftest-plan-001
1657+
title: Selftest Plan
1658+
owner: selftest
1659+
created_at: 2026-02-13T00:00:00Z
1660+
version: 1
1661+
---
1662+
1663+
# Plan
1664+
1665+
- [x] 1. Preserve previously completed setup
1666+
- [ ] 2. Execute pending task
1667+
- [ ] 3. Capture final checkpoint
1668+
""",
1669+
encoding="utf-8",
1670+
)
1671+
1672+
start_work = subprocess.run(
1673+
[
1674+
sys.executable,
1675+
str(START_WORK_SCRIPT),
1676+
str(plan_path),
1677+
"--deviation",
1678+
"manual verification note",
1679+
"--json",
1680+
],
1681+
capture_output=True,
1682+
text=True,
1683+
env=refactor_env,
1684+
check=False,
1685+
cwd=REPO_ROOT,
1686+
)
1687+
expect(start_work.returncode == 0, "start-work should execute valid plan")
1688+
start_work_report = parse_json_output(start_work.stdout)
1689+
expect(
1690+
start_work_report.get("status") == "completed",
1691+
"start-work should report completed status for fully executed plan",
1692+
)
1693+
expect(
1694+
start_work_report.get("step_counts", {}).get("completed") == 3,
1695+
"start-work should complete all plan steps",
1696+
)
1697+
expect(
1698+
start_work_report.get("deviation_count", 0) >= 2,
1699+
"start-work should capture precompleted and manual deviations",
1700+
)
1701+
1702+
start_work_status = subprocess.run(
1703+
[sys.executable, str(START_WORK_SCRIPT), "status", "--json"],
1704+
capture_output=True,
1705+
text=True,
1706+
env=refactor_env,
1707+
check=False,
1708+
cwd=REPO_ROOT,
1709+
)
1710+
expect(start_work_status.returncode == 0, "start-work status should succeed")
1711+
start_work_status_report = parse_json_output(start_work_status.stdout)
1712+
expect(
1713+
start_work_status_report.get("status") == "completed",
1714+
"start-work status should persist latest run status",
1715+
)
1716+
1717+
start_work_deviations = subprocess.run(
1718+
[sys.executable, str(START_WORK_SCRIPT), "deviations", "--json"],
1719+
capture_output=True,
1720+
text=True,
1721+
env=refactor_env,
1722+
check=False,
1723+
cwd=REPO_ROOT,
1724+
)
1725+
expect(
1726+
start_work_deviations.returncode == 0,
1727+
"start-work deviations should succeed",
1728+
)
1729+
start_work_deviation_report = parse_json_output(start_work_deviations.stdout)
1730+
expect(
1731+
start_work_deviation_report.get("count", 0) >= 2,
1732+
"start-work deviations should return captured deviation entries",
1733+
)
1734+
1735+
invalid_plan_path = tmp / "invalid_plan_execution_selftest.md"
1736+
invalid_plan_path.write_text(
1737+
"""---
1738+
id: invalid-plan-001
1739+
title: Invalid Plan
1740+
owner: selftest
1741+
created_at: 2026-02-13T00:00:00Z
1742+
version: 1
1743+
---
1744+
1745+
# Plan
1746+
1747+
- [ ] validate command wiring without ordinal
1748+
""",
1749+
encoding="utf-8",
1750+
)
1751+
invalid_start_work = subprocess.run(
1752+
[sys.executable, str(START_WORK_SCRIPT), str(invalid_plan_path), "--json"],
1753+
capture_output=True,
1754+
text=True,
1755+
env=refactor_env,
1756+
check=False,
1757+
cwd=REPO_ROOT,
1758+
)
1759+
expect(
1760+
invalid_start_work.returncode == 1,
1761+
"start-work should fail invalid plan artifacts",
1762+
)
1763+
invalid_start_work_report = parse_json_output(invalid_start_work.stdout)
1764+
expect(
1765+
invalid_start_work_report.get("code") == "validation_failed",
1766+
"start-work should report validation_failed for invalid plan format",
1767+
)
1768+
16521769
keyword_report = resolve_prompt_modes(
16531770
"Please safe-apply and deep-analyze this migration; ulw can wait.",
16541771
enabled=True,

0 commit comments

Comments
 (0)