@omnicoreos/planka-mcp 0.2.0

package/workflow/README.md

@@ -0,0 +1,232 @@
+# A board that survives the session
+
+This is an optional working method built around the MCP server in this repository.
+You do not need it to use the 24 Planka tools.
+
+## The problem it solves
+
+A fresh agent session does not know why a task exists, what was already tried, or
+which decision unblocked it. That state usually lives in one person's head. The
+result is repeated investigation, stale branches, and a human who has to reconstruct
+every workstream on demand.
+
+This proposal moves that state into a Planka board. The board is not a backlog that
+the human must maintain. It is the durable handoff between conversations, agents,
+branches, and worktrees.
+
+Adopt it in layers:
+
+1. Use only the MCP server.
+2. Add the board states and card format.
+3. Add parallel worktrees with a director and one worker per card.
+
+Stop at the layer that helps. The method is a starting point, not a doctrine.
+
+## Core rules
+
+1. **The conversation is the input.** The human explains a bug or feature. The
+   agent writes the card. The board mirrors work; it is not a form the human fills.
+2. **Columns describe verifiable repository state.** A card in `In worktree` has a
+   real branch and worktree. A card in `Merged` is in the base branch and verified.
+3. **Read every comment before touching a card.** The description says how the task
+   started. Comments say what is true now. The newest human decision wins.
+4. **One writer per worktree.** In parallel mode, the worker assigned to a card is
+   the only agent that edits its branch. The director coordinates and audits.
+5. **Evidence travels with the card.** Checks, manual verification, remaining risk,
+   and the commit or branch are recorded before a session ends.
+
+## Board states
+
+The bootstrap script creates these lists:
+
+| List | Verifiable meaning | Owner of the transition |
+|---|---|---|
+| `Pending` | Described, but no branch or worktree exists | Director |
+| `Needs your decision` | One concrete product or risk choice blocks work | Director puts it here; human unlocks it |
+| `In worktree` | The metadata points to a live branch and worktree | Director |
+| `Test it` | Pre-merge human judgment is genuinely required | Director after worker evidence |
+| `Review in main` | Merged, but the final proof only exists on the integrated branch or environment | Director; human confirms |
+| `Merged` | In the base branch, closure recorded, and required verification complete | Director |
+
+Do not use columns as moods such as “almost done.” If repository state and board
+state disagree, fix the board immediately.
+
+## Human handshakes
+
+### `decided`
+
+For a card in `Needs your decision`, the human:
+
+1. leaves a comment containing the decision;
+2. applies the `decided` label.
+
+The agent does not infer the decision from the label alone. It reads all comments,
+treats the newest human decision as binding, rewrites the description so the chosen
+scope is self-contained, and then moves the card to `Pending` or `In worktree`.
+
+Only a human applies `decided`. Keep the label as durable provenance.
+
+### `tested-ok`
+
+For a card in `Review in main`, the human applies `tested-ok` after checking the
+integrated behavior. The director then moves it to `Merged`. If the check fails, the
+human comments with the observed behavior and the director creates or reopens a fix.
+
+Only a human applies `tested-ok`.
+
+## Card anatomy
+
+Use the copyable template in [board-template.md](board-template.md). A useful card
+answers five questions in ordinary language:
+
+- What is happening?
+- How can someone see or reproduce it?
+- Where does it live?
+- What proves it is done?
+- What could this change break?
+
+At the bottom, a machine-readable comment links the card to Git:
+
+```html
+<!-- agent-work
+branch: agent/fix-export-timeout
+worktree: .worktrees/fix-export-timeout
+port: 4173
+plan: docs/plans/fix-export-timeout.md
+-->
+```
+
+Omit fields that do not apply. The card remains the source of truth for the
+card-to-branch-to-worktree relationship.
+
+## Labels are instructions
+
+The template uses a deliberately small behavior vocabulary:
+
+| Label | Agent behavior |
+|---|---|
+| `needs-decision` | Stop implementation and ask one concrete question |
+| `decided` | Read the human decision in comments and prioritize the card |
+| `tested-ok` | Human confirmed the post-merge check |
+| `fast-track` | Small, low-risk change; use the repository's short verification path |
+| `standard` | Normal planning, implementation, and verification path |
+| `serial` | Run alone because it touches shared or irreversible state |
+| `zone:*` | Mutual-exclusion key for parallel work |
+
+Two cards with the same `zone:*` label never run in parallel. Tune zones to your
+repository boundaries. The starter set is only an example.
+
+Use `serial` for migrations, shared test fixtures, global infrastructure, or any
+verification that mutates one shared environment.
+
+## Director and workers
+
+Parallel mode separates coordination from editing.
+
+### Director
+
+The director:
+
+- reads the complete board and every candidate card's comments;
+- chooses eligible cards, respecting `serial` and `zone:*` exclusions;
+- creates branches and worktrees;
+- writes the card metadata;
+- gives each worker one bounded brief;
+- audits evidence and decides the next board state;
+- serializes merges and cleans worktrees.
+
+In this contract, the director does not edit repository files. This keeps ownership
+clear and makes a worker's evidence first-hand rather than reconstructed.
+
+### Worker
+
+One worker owns one card and one worktree. It:
+
+- edits only that worktree;
+- follows the repository's own instructions;
+- runs the relevant checks;
+- performs the acceptance steps from the card;
+- captures visual evidence when the change is visual;
+- commits its work;
+- writes progress and closure only on its assigned card.
+
+A worker does not select other cards, move unrelated cards, merge the base branch,
+or invent human approval.
+
+### Worker brief
+
+A director should provide:
+
+```text
+Mission: one concrete outcome
+Card: title, current description, and every relevant comment
+Worktree: absolute path and branch
+Acceptance: exact observable proof
+Required checks: repository-specific commands
+Do not: scope boundaries and external side effects
+Output: commit, checks, manual proof, risks, and closing comment
+```
+
+If a worker needs correction, continue the same worker session when the runtime
+supports it. Replacing it loses the context the board/worktree contract is trying to
+preserve.
+
+## Automatic progress and vetoes
+
+Verified work may merge without another ceremony when all required evidence is
+present and the repository allows it. Keep explicit vetoes for work where automated
+confidence is not enough:
+
+- access control, visibility, or security boundaries;
+- destructive migrations or shared production-like data;
+- money, billing, or irreversible external side effects;
+- infrastructure that competes with a human's active environment;
+- physical hardware or third-party approval that the worker cannot exercise.
+
+A veto does not mean “never.” It means stop at `Test it` or `Review in main` with an
+exact question or check. “Please test” without saying what remains uncertain is not
+evidence.
+
+## Closure evidence
+
+The worker leaves a comment like this before handing the card back:
+
+```markdown
+✅ Ready for review
+
+**Changed:** <one user-visible sentence>
+
+**Where to check:** <URL, command, or exact path>
+
+**Prove it:** <one concrete acceptance step>
+
+**Risk:** <real nearby behavior that could regress>
+
+**Verified:** <checks and manual evidence, with honest omissions>
+
+**Commit:** <commit SHA>
+```
+
+The director audits the claim against the branch, checks, and attachments. It does
+not silently upgrade “not tested” into “passed.”
+
+## A safe cycle
+
+1. Read the board and comments.
+2. Prefer `decided` cards whose zones are free.
+3. Apply `serial` and zone exclusions.
+4. Create one worktree per selected card and update metadata.
+5. Dispatch one worker per worktree.
+6. Workers implement, verify, commit, and comment.
+7. Director audits and chooses `Test it`, `Review in main`, or merge.
+8. Merge one worktree at a time.
+9. Confirm the board, base tree, and worktree inventory agree.
+
+The optional [worktree helper](worktrees/README.md) automates the Git mechanics. It
+does not decide whether a card is safe to run or merge.
+
+## Start small
+
+For a first trial, use one board and one card. Ask the agent to create a card from a
+conversation, read it back, implement in one branch, and leave the closure comment.
+Add parallelism only after that loop feels boring and reliable.

package/workflow/board-template.md

@@ -0,0 +1,115 @@
+# Board template
+
+Create the optional workflow on an empty board:
+
+```bash
+export PLANKA_BASE_URL="https://planka.example.com"
+export PLANKA_AGENT_EMAIL="agent@example.com"
+export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
+
+node scripts/bootstrap-board.mjs --board-id "<BOARD_ID>"
+```
+
+Or create the board inside a project and then bootstrap it:
+
+```bash
+node scripts/bootstrap-board.mjs \
+  --project-id "<PROJECT_ID>" \
+  --board-name "Agent Work"
+```
+
+The command is idempotent. It fills missing template lists and labels. It refuses to
+alter an unrelated populated board unless you pass `--force` deliberately.
+
+## Lists
+
+| Order | Name | Repository invariant |
+|---:|---|---|
+| 1 | `Pending` | No branch or worktree exists |
+| 2 | `Needs your decision` | A human answer is required |
+| 3 | `In worktree` | Branch and worktree exist |
+| 4 | `Test it` | Human proof is required before merge |
+| 5 | `Review in main` | Merged; final integrated proof is pending |
+| 6 | `Merged` | Integrated and verified |
+
+`Merged` is created as a Planka `closed` list. The others are `active` lists.
+
+## Labels
+
+| Label | Meaning |
+|---|---|
+| `needs-decision` | Implementation is blocked on one human choice |
+| `decided` | Human decision is in the comments |
+| `tested-ok` | Human approved the integrated result |
+| `fast-track` | Repository-defined lightweight path |
+| `standard` | Normal verification path |
+| `serial` | Never run beside another worktree |
+| `zone:frontend` | Frontend ownership boundary |
+| `zone:backend` | Backend ownership boundary |
+| `zone:data` | Data/schema boundary |
+| `zone:infra` | Infrastructure/global-state boundary |
+| `zone:shared-ui` | Shared design-system boundary |
+
+Rename or add zones to match your repository. The important contract is that two
+cards with the same zone do not run concurrently.
+
+## Card description
+
+```markdown
+## What is happening
+One or two sentences from the user's point of view.
+
+## How to see it
+Exact reproduction steps or the place to inspect.
+
+## Where it lives
+- path/to/likely-file.ts
+- path/to/related-test.ts
+
+## Done means
+Observable acceptance criteria.
+
+## Risk
+Nearby behavior or data that could regress.
+
+<!-- agent-work
+branch: agent/short-slug
+worktree: .worktrees/short-slug
+port:
+plan:
+-->
+```
+
+The description captures current scope. Comments preserve decisions, attempts,
+evidence, and handoffs over time.
+
+## Decision request
+
+Ask one question, not a questionnaire:
+
+```markdown
+🚧 Decision needed
+
+Should an archived item remain visible to administrators, or disappear for every
+role? This changes the access boundary, so implementation is paused.
+```
+
+The human replies in a comment and applies `decided`.
+
+## Closing comment
+
+```markdown
+✅ Ready for review
+
+**Changed:** Export now reports a useful timeout instead of hanging.
+
+**Where to check:** Settings → Exports → Start export
+
+**Prove it:** Start an export against the slow test fixture and confirm it stops with the timeout message.
+
+**Risk:** Normal exports and retry behavior share the same request path.
+
+**Verified:** unit tests ✅ · typecheck ✅ · manual slow-fixture check ✅
+
+**Commit:** abc1234
+```

package/workflow/skills/planka-close-card/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: planka-close-card
+description: This skill should be used when the user asks to "close this Planka card", "ship this card", "finish the card", "record the card handoff", or confirms "tested ok" for a workflow card. It verifies evidence, records a durable closing comment, and performs only the merge or board transition owned by the current role.
+version: 0.1.0
+---
+
+# Close a Planka workflow card
+
+Closure is evidence plus a truthful state transition. Do not move a card merely
+because implementation stopped.
+
+## Read first
+
+1. Read the card description and every comment.
+2. Read the repository's contribution and verification instructions.
+3. Resolve the `<!-- agent-work -->` branch and worktree against real Git state.
+4. Determine your role:
+   - worker: edits, verifies, commits, and writes the handoff;
+   - director: audits, merges, cleans, and changes board state;
+   - human confirmation handler: records `tested-ok` and completes the final move.
+
+Do not perform another role's transition unless the user explicitly assigned both
+roles and the repository allows it.
+
+## Worker closure
+
+The worker must:
+
+1. Run the relevant repository checks.
+2. Execute the card's observable acceptance step.
+3. Capture visual evidence when the change is visual.
+4. Record any skipped or impossible proof explicitly.
+5. Commit all intended files and confirm the worktree is clean.
+6. Leave this comment on the assigned card:
+
+```markdown
+✅ Ready for review
+
+**Changed:** <one user-visible sentence>
+
+**Where to check:** <URL, command, or exact path>
+
+**Prove it:** <one concrete acceptance step>
+
+**Risk:** <real nearby behavior that could regress>
+
+**Verified:** <checks and manual evidence, with honest omissions>
+
+**Commit:** <commit SHA>
+```
+
+The worker does not merge, delete the worktree, or move unrelated cards.
+
+## Director closure
+
+The director verifies:
+
+- commit and important diff match the card;
+- required checks are green;
+- acceptance evidence is first-hand and specific;
+- risk and omissions are explicit;
+- worker and base trees are clean;
+- no veto requires human judgment.
+
+Then choose exactly one destination:
+
+- merge and `Merged` when verification is complete;
+- `Test it` when human judgment is needed before merge;
+- merge and `Review in main` when only integrated proof remains;
+- stay `In worktree` with a concrete red result when implementation is incomplete.
+
+Use the supported merge helper. Never bypass its clean-tree, conflict, or verification
+guards. After merge, confirm the branch/worktree cleanup and board state agree.
+
+## Human confirmation
+
+For a card in `Review in main`, an explicit human confirmation or human-applied
+`tested-ok` is authorization to move it to `Merged`. If the human reports a failure,
+comment with the observation and open or restore a fix card instead.
+
+Never apply `tested-ok` or `decided` on behalf of the human.

package/workflow/skills/planka-orchestrator/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: planka-orchestrator
+description: This skill should be used when the user asks to "orchestrate the Planka board", "run cards in parallel", "act as the director", "dispatch workers from Planka", or "continue the board workflow". It coordinates cards, comments, worktrees, worker ownership, evidence, and safe merges without editing repository files in the director role.
+version: 0.1.0
+---
+
+# Planka workflow orchestrator
+
+Use this skill only for the optional workflow documented in `workflow/README.md`.
+The Planka MCP server must be connected and the repository must define its own build,
+test, review, and merge rules.
+
+## Role boundary
+
+You are the director. Do not edit repository files. Workers are the only writers:
+one worker, one card, one branch, one worktree.
+
+The director may:
+
+- read the repository and board;
+- create and update cards;
+- create worktrees with the repository's supported helper;
+- dispatch or continue workers;
+- audit diffs, commits, checks, comments, and attachments;
+- merge through the repository's supported path;
+- clean completed worktrees.
+
+## Preflight
+
+1. Read the repository's agent instructions and workflow documentation.
+2. Check the base tree and current worktrees without changing them.
+3. Read the full board.
+4. For every candidate card, read the description and all comments in order.
+5. Confirm the card has acceptance criteria and one behavior label.
+6. Resolve `serial` and `zone:*` exclusions before creating anything.
+
+Never trust a suspicious zero-comment result blindly. If the card's state implies a
+decision or prior work, use `planka_get_comments` and report an MCP/API mismatch.
+
+## Selection
+
+Choose cards in this order:
+
+1. Cards in `Needs your decision` with a human-applied `decided` label.
+2. Eligible `Pending` cards whose zones are free.
+3. At most the concurrency limit supported by the repository and machine.
+
+Do not select:
+
+- a card whose required decision is absent or ambiguous;
+- two cards with the same `zone:*` label;
+- any second card beside a `serial` card;
+- work requiring credentials, hardware, external approval, or irreversible changes
+  that the worker cannot verify safely.
+
+For a `decided` card, read the newest human decision, treat it as binding, and update
+the description so the chosen scope can be understood without reconstructing the
+comment thread. Never apply `decided` or `tested-ok` yourself.
+
+## Dispatch
+
+For each selected card:
+
+1. Create the branch and worktree using the repository helper.
+2. Update the card's `<!-- agent-work -->` metadata.
+3. Move the card to `In worktree` only after the Git state exists.
+4. Dispatch one worker from inside that worktree.
+
+The worker brief must contain:
+
+- exact mission and acceptance criteria;
+- the complete current card context, including decisions;
+- allowed repository scope and explicit exclusions;
+- worktree path and branch;
+- required checks and manual verification;
+- required closing comment and commit evidence.
+
+Workers may use their own bounded subagents, but only one worker session owns writes
+to the worktree. If correction is needed, continue the same session when possible.
+
+## Audit
+
+Audit, do not recreate, the worker's evidence:
+
+- inspect the commit and important diff;
+- confirm required checks actually ran and passed;
+- confirm the acceptance step matches the card;
+- inspect visual evidence when the behavior is visual;
+- confirm the closing comment states omissions and remaining risk honestly;
+- confirm the worker changed only its assigned scope.
+
+If evidence is incomplete, leave a concrete comment and continue the same worker with
+one targeted request. Do not mark a theory as a verified result.
+
+## Destination
+
+- Merge when repository checks and acceptance evidence are complete and no veto
+  applies.
+- Use `Test it` when a human must judge something before merge. State exactly what
+  to inspect and why the worker could not settle it.
+- Merge to `Review in main` when all pre-merge evidence exists but the final proof
+  only exists in the integrated environment. State the exact post-merge check.
+- Use `Needs your decision` for product, access, cost, or irreversible choices. Ask
+  one concise question.
+
+Security/access boundaries, destructive data operations, billing, shared
+infrastructure, physical hardware, and third-party approvals are human gates unless
+the repository explicitly defines a safe automated proof.
+
+## Merge and close
+
+Merge one worktree at a time through the repository's supported helper. Before merge:
+
+- worker tree clean;
+- worker commits exist;
+- base tree clean;
+- required checks and acceptance evidence recorded;
+- card metadata matches the actual branch and worktree.
+
+After merge, remove the worktree through the helper and make the board match reality.
+Move directly to `Merged` only when all required verification is complete. A card in
+`Review in main` moves to `Merged` only after a human applies `tested-ok` or gives an
+equivalent explicit confirmation.
+
+End with a compact report: cards selected, cards merged, cards waiting for a human,
+checks, worktrees still alive, and any board/repository mismatch.

package/workflow/worktrees/README.md

@@ -0,0 +1,104 @@
+# Optional worktree helper
+
+`wt.sh` is a conservative example for running one agent worker per Git worktree.
+It manages Git mechanics; it does not choose cards or decide that a merge is safe.
+
+The script has no built-in port range, package manager, dev command, environment
+copy, or dependency install. Configure only what your repository needs.
+
+## Install
+
+From your repository root:
+
+```bash
+mkdir -p scripts
+cp workflow/worktrees/wt.sh scripts/wt.sh
+chmod +x scripts/wt.sh
+cp workflow/worktrees/wt.conf.example .agent-worktrees.conf
+```
+
+Review `.agent-worktrees.conf` before use. Commit the script and config if they are
+part of your team's contract. Add `.worktrees/` to `.gitignore`.
+
+## Commands
+
+```bash
+scripts/wt.sh new fix-export-timeout
+scripts/wt.sh up fix-export-timeout
+scripts/wt.sh list
+scripts/wt.sh doctor
+scripts/wt.sh merge fix-export-timeout
+scripts/wt.sh kill fix-export-timeout
+```
+
+`merge` performs a local `--no-ff` merge and never pushes.
+
+## Development command discovery
+
+If `WT_DEV_COMMAND` is empty, the helper looks for a `dev` script in
+`package.json` and chooses a command from the repository lockfile:
+
+| Lockfile | Command |
+|---|---|
+| `package-lock.json` | `npm run dev` |
+| `pnpm-lock.yaml` | `pnpm run dev` |
+| `yarn.lock` | `yarn dev` |
+| `bun.lock` or `bun.lockb` | `bun run dev` |
+
+Set an explicit command for non-Node repositories or unusual scripts:
+
+```bash
+WT_DEV_COMMAND='make dev'
+```
+
+If the command needs a port, set `WT_PORT_START` and use `{port}` or read the `PORT`
+environment variable:
+
+```bash
+WT_PORT_START=4100
+WT_MAX_WORKTREES=4
+WT_DEV_COMMAND='npm run dev -- --port {port}'
+```
+
+The numbers are examples in the config, not behavior compiled into the script.
+
+## Environment safety
+
+The helper does not copy `.env`. Parallel processes can duplicate queue consumers,
+scheduled jobs, webhooks, billing calls, or production writes.
+
+If a worktree needs environment values, create a reviewed safe template and opt in:
+
+```bash
+WT_ENV_TEMPLATE=.env.worktree
+WT_ENV_TARGET=.env
+```
+
+Do not point `WT_ENV_TEMPLATE` at a production credential file. Disable background
+workers and external side effects in the template itself.
+
+## Dependency setup
+
+Set `WT_INSTALL_COMMAND` when each worktree needs its own dependencies:
+
+```bash
+WT_INSTALL_COMMAND='npm ci'
+```
+
+Leave it empty when your repository has another supported strategy. The helper does
+not symlink dependency directories because that is not safe for every package manager.
+
+## Safety model
+
+- Slugs accept only lowercase letters, numbers, and hyphens.
+- The base tree and worker tree must be clean before merge.
+- A worker must contain commits not yet in the base branch.
+- A configured development port must be free before start and stopped before merge.
+- Merges are serialized with an atomic directory lock that works on macOS and Linux.
+- Conflicts are resolved in the worker branch, never half-applied in the base tree.
+- `kill` preserves unmerged work unless `--force` is explicit.
+- No command pushes.
+
+`doctor` reports files modified by more than one live worktree. This is an early
+warning, not a conflict resolver. The board's `zone:*` rule should prevent most of
+these overlaps before Git sees them.

package/workflow/worktrees/wt.conf.example

@@ -0,0 +1,24 @@
+# Copy this file to .agent-worktrees.conf in your repository root.
+
+# Defaults to the remote default branch, then main/master, then the current branch.
+WT_BASE_BRANCH=
+
+# Defaults shown here are paths/names, not environment-specific ports.
+WT_ROOT=.worktrees
+WT_BRANCH_PREFIX=agent/
+WT_MAX_WORKTREES=4
+
+# Leave empty to run without assigned ports. If set, each worktree receives the
+# first free port starting here and `up` exports PORT. Use {port} in the command
+# when your dev CLI needs an explicit argument.
+WT_PORT_START=
+
+# Leave empty to discover package.json#scripts.dev and the package manager lockfile.
+WT_DEV_COMMAND=
+
+# Optional command run once inside a newly created worktree.
+WT_INSTALL_COMMAND=
+
+# Environment copying is opt-in. Point only at a reviewed, worktree-safe template.
+WT_ENV_TEMPLATE=
+WT_ENV_TARGET=.env