Skip to content

porting-plan.md

Latest commit

 

History

History
150 lines (127 loc) · 10.2 KB

porting-plan.md

File metadata and controls

150 lines (127 loc) · 10.2 KB
Raw

Porting plan

Status: draft v0.1 · 2026-07-27

Source material lives in the originating project's .claude/ directory (assumed available as a sibling checkout, e.g. ../adguard-wallet). Each phase leaves the repo in a coherent, committable state. Genericization rules are defined in design.md.

Phase 0 — skeleton ✅

Repo scaffold, plugin manifest, marketplace file, docs. (This commit.)

Phase 1 — contracts and config layer

The rules everything else obeys, plus the config mechanism they will reference.

  • Define .artel/config.json schema (ticket grammar, tracker/VCS adapters, verify commands, language, specs dir) + a documented default → config.md.
  • Port and genericize ticket-parsing.md (ticket-ID grammar → config-driven) → ticket-parsing.md.
  • Port and genericize autonomous-run.md (run state, modes, caps) — host-writable state moves to .artel/run/ → autonomous-run.md.
  • Port orchestrator-common.md (the skill-orchestrator contract) → orchestrator-common.md.

Phase 2 — agents

  • Port the crew (12): analyst, figma-analyst, researcher, planner, task-planner, tasklist-writer, vision-writer, implementer, reviewer, qa, validator, tech-writer.
  • Strip source-project specifics (Flutter/Dart tool references, Jira project key, Bitbucket MCP tool names) → config lookups or adapter instructions.
  • Port and genericize the agent-crew contracts consumed by every agent: deviation-protocol.md, path-conventions.md → docs/.

Phase 3 — stage skills

  • Port à-la-carte stage skills: analysis, researcher, planner, tasklist, generate-idea, generate-vision, generate-tasklist, implementer, run-reviewer, qa, docs-update, validate, pr-description, pr-create, sync-phases, figma-analysis, change-digest, address-pr-comment.
  • Port with rename: flutter-inner-loop → inner-loop (verify commands from config), wallet-review → deep-review (dual reviewer; tracker/VCS via adapters), jira-issue-ru → issue-draft (output language from config).
  • Port runtime-gate skills as config-driven adapters: run-app, drive-app (launch/drive commands from config; RUNTIME_OK degrades to "skipped" when unconfigured), plus add-automation / remove-automation (scaffold commands from config). Follow-up from Task 3: the source implementer skill had an on-demand runtime-check hint for mid-implementation debugging, distinct from the RUNTIME_OK completion gate; the port dropped it (Dart/Flutter-specific, no run-app to point at yet) — when run-app lands, decide whether implementer (agent + skill) should regain a generic runtime.run / /artel:run-app on-demand reference. Resolved in the run-app port: restored as a one-line optional hint in skills/implementer/SKILL.md's dispatch prompt (/artel:run-app via runtime.run, explicitly not the RUNTIME_OK gate).
  • Port ops & utility skills: init-branch, merge-conflicts, save-context, restore-context (store path → artel), agents-md-generator. Follow-up from Task 7: the source init-branch ran a post-branch dependency-install/codegen step; no generic config key covers it — decide in Phase 4/5 (init interview / hooks config) whether a setup-command key is warranted. Resolved in Phase 4: setup.commands added to config.md and the step restored in init-branch.
  • Each skill resolves ticket context → invokes its agent → reports (no inlined work), except the self-declared procedural workers (sync-phases, generate-idea, merge-conflicts, etc.), which have no matching agent and run their documented procedure inline instead.
  • Phase-2 review follow-ups (fold into the matching skill ports): add review/findings.json and the ticket verify/ evidence dir to ticket-parsing.md §3/§4 (with run-reviewer / inner-loop); uniform "(Phase 3)"/"(Phase 5)" forward-reference labels across agent bodies (figma-analyst's template path lacks one); planner.md's design-doc citation → ${CLAUDE_PLUGIN_ROOT}/docs/design.md form; reconcile reviewer.md's "PR review approval" checkbox with the tasklist template (with tasklist); consider a specs.releases config key for the specs/releases/ literal kept (with caveat) in qa.md/validator.md.

Phase 4 — entry-point orchestrators

  • Port feature-development (full pipeline, one approval pause, resumability).
  • Port dev (lean loop: work-list confirmation → implement + review + runtime gate).
  • First-run init interview: no config found → interview → write .artel/config.json. Shipped as the setup skill (/artel:setup) — see design.md's decision log for the naming.

Phase 5 — hooks and gates

  • Port Python hooks: session_baseline, fast_verify_post_edit, stop_gate, verify_stop_gate, sensitive_guard, hook_common.
  • Wire via hooks/hooks.json with ${CLAUDE_PLUGIN_ROOT} paths.
  • Verify commands come from config, not make/Dart assumptions — scripts/verify.py wraps verify.fast/verify.commands in the envelope contract; new verify.surface key + {files} placeholder (config.md).
  • Decide the deterministic-CLI question (design.md open question 1) and implement — Python verify + plan-check under scripts/; codegen dropped (see decision log and the map below).

Phase 6 — publish

  • End-to-end dry run in a scratch repo (a trivial non-Dart project). A Flutter-host smoke test is documented separately in testing-flutter.md (parity with the source system); the non-Dart run remains the genericization proof.
  • Operator docs: adapt workflow-guide.md + skills-reference.md to plugin reality → workflow-guide.md, skills-reference.md. Alongside: README refreshed to ported-pre-publish reality, hooks/README.md rewritten to describe the shipped hooks, stale "later phase"/"Phase 5" forward references resolved across contracts and agent bodies.
  • Push to GitHub, verify /plugin marketplace add dseloustev/artel install path.
  • Tag v0.1.0. Released and tagged through v0.11.0 (2026-09-05); bump-version owns the chore.

Finding from the docs reader-test (2026-08-08), fixed 2026-09-05 before the dry run: under tracker.adapter: "none", feature-development's gate 0 relied on a description file or an existing idea.md but never invoked generate-idea to create one, while generate-vision (gate 2) hard-requires idea.md — so a "none"-tracker run errored at the vision gate. Gate 0 now invokes generate-idea under every adapter (the skill already branches on tracker.adapter internally); see the design.md decision log.

Source → plugin map

Source (.claude/…) Plugin Action
skills/feature-development, skills/dev skills/ port + genericize (Phase 4)
skills/{analysis,researcher,planner,tasklist,implementer,run-reviewer,qa,docs-update,validate,pr-description,pr-create,sync-phases,generate-idea,generate-vision,generate-tasklist,figma-analysis,change-digest,address-pr-comment} skills/ port + genericize (Phase 3)
skills/flutter-inner-loop → inner-loop, skills/wallet-review → deep-review, skills/jira-issue-ru → issue-draft skills/ port + rename + genericize (Phase 3)
skills/{run-app,drive-app,add-automation,remove-automation} skills/ port as config-driven adapters (Phase 3)
skills/{init-branch,merge-conflicts,save-context,restore-context,agents-md-generator} skills/ port + genericize (Phase 3)
skills/{flutter-*,dart-*} (informational how-tos) likbez plugin separate repo, seeded from source
skills/{move-to-windsurf,restore-from-windsurf} — skip: superseded by save-context/restore-context
agents/*.md (crew of 12, incl. figma-analyst) agents/ port + genericize (Phase 2)
agents/docs/ticket-parsing.md docs/ port + genericize (Phase 1)
agents/docs/{deviation-protocol,path-conventions}.md docs/ port + genericize (Phase 2)
docs/{autonomous-run,orchestrator-common}.md docs/ port + genericize (Phase 1)
docs/{workflow-guide,skills-reference}.md docs/ adapt (Phase 6)
hooks/*.py hooks/ port + config-driven verify (Phase 5)
rules/sensitive-paths.json hooks/sensitive-paths.json generic default categories (secrets, gate-config, ci-cd); host override at .artel/sensitive-paths.json (Phase 5)
tools/agent/ (Dart CLI) scripts/ Python rewrite: verify, plan-check (Phase 5); codegen dropped — detection rules were Dart-specific, setup.commands covers install/codegen; dcm subsumed by config-driven verify.commands
tools/launch_app.dart + tools/templates/ — replaced by config-driven launch/scaffold commands behind run-app/drive-app/add-automation (Phase 3/5)
rules/ast-index.md, Dart MCP rules likbez plugin index-refresh in orchestrators becomes an optional config hook

Phase 7 — OpenCode host

Generator + bridge plugin + installer, with Claude Code preserved byte-for-byte on the canonical files. Design: docs/superpowers/specs/2026-08-26-opencode-host-design.md (local); committed record: the design.md decision log and docs/opencode.md.

  • Generator: scripts/build_opencode.py — artel--prefixed skills, command wrappers, agents, glossary, baked root; tests/test_build_opencode.py.
  • Bridge plugin: opencode/plugin/artel.ts — tool hooks (sensitive guard, fast verify, knowledge mirror) + session lifecycle (baseline, router injection, stop-gate idle re-prompt).
  • Installer: scripts/install-opencode.sh (install / --remove).
  • Docs: docs/opencode.md, README install section, hooks/README bridge note, autonomous-run.md OpenCode headless note.
  • E2E smoke on OpenCode + Claude Code regression.
  • Release 0.7.0.