allye-pi 1.8.0 → 2.1.0

package/skills/board-progression/SKILL.md

@@ -1,214 +0,0 @@
----
-name: board-progression
-description: Rules for moving work items between statuses in Allye boards. Covers work_status_next, work_status_done, and status categories.
-version: "1.2"
-category: methodology
----
-
-# Board Progression
-
-How to move work items between statuses on Allye boards, correctly.
-
----
-
-## 1. Status Categories vs. Status Names
-
-The MCP client can only **confirm** 4 status categories — `work_statuses()` (`work_items.py`) groups every status under a hardcoded `category_order`:
-
-| Category (confirmed) | Meaning |
-|----------|---------|
-| `proposed` | Not yet started (backlog/todo-like) |
-| `in_progress` | Actively being worked on |
-| `done` | Completed and verified |
-| `cancelled` | Will not be done |
-
-That's the only taxonomy the MCP client source guarantees. Specific status **names** are team-configurable `WorkflowStatus` records mapped onto those 4 categories via board columns — not enumerable or guaranteed from the client code alone, and a given team's board may use different names or skip some of them.
-
-### The team's pipeline is data. Read it.
-
-Allye is multi-tenant. Four presets ship — Solo, Startup, Standard, Enterprise — and every
-team customises from there, so **there is no status list to memorise and no ordering to
-assume.** A skill that names a status has guessed about somebody else's board.
-
-Only three things are stable enough to build a rule on:
-
-| Stable | Why |
-|---|---|
-| The four categories: `proposed`, `in_progress`, `done`, `cancelled` | A schema enum. Every status maps to exactly one. |
-| The three pipelines: `product`, `engineering`, `shared` | A schema enum. `product` carries epics and features; `engineering` carries stories and below; `shared` holds the terminal states. |
-| The board's own ordering | Whatever it is, it is what `work_status_next` walks. |
-
-Discover the rest:
-
-```
-work_statuses()    → every status the team has, grouped by category, in position order
-board_columns()    → the columns of a specific board
-```
-
-**Two things `work_statuses()` does not tell you today**, and planning around them is the
-difference between a working transition and a surprised one:
-
-- **`position`, `pipeline`, and `description` are not returned.** They exist on the record —
-  the seed writes all three — but the MCP formatter emits only name, key, id, and colour.
-- **`board_columns()` returns names and ids only** — no status-to-column mapping and no
-  ordering. The visible subset a given board shows cannot be reconstructed from it.
-
-Together these mean **you cannot reliably predict the next status.** So do not:
-
-<HARD-GATE>
-Move one status at a time, then **read back** the status you actually landed on. Never
-assume a transition took you where you expected, and never chain several moves on a
-prediction. One extra read per transition costs nothing next to a cascade that silently
-skipped four gates.
-</HARD-GATE>
-
-For reference only, these are the eighteen statuses the presets seed — **an example of one
-tenant's configuration, not a list to code against**: `idea`, `researching`, `designing`,
-`specifying`, `backlog`, `todo`, `in_progress`, `code_review`, `security_scan`, `qa_testing`,
-`doc_review`, `deploy_staging`, `qa_staging`, `deploy_preprod`, `qa_preprod`, `deploy_prod`,
-`done`, `cancelled`.
-
----
-
-## 2. How `work_status_next` Works
-
-`work_status_next` moves a work item to the **next logical status** in the board progression.
-
-### Resolution logic
-
-1. Collects all visible statuses from non-archived boards
-2. Orders them by: `board.position → column.position → BoardColumnStatus.position`
-3. Deduplicates: first occurrence wins
-4. Finds the current status in this ordered list
-5. Moves to the next status in the list
-
-### Edge cases
-
-| Situation | Behavior |
-|-----------|----------|
-| Current status is NOT in any visible board | Moves to the **first** status in the list |
-| Current status is the **last** in the list | Returns an **error** — cannot move forward |
-| Item has no status set | Moves to the **first** status in the list |
-
-### When to use
-
-```
-work_status_next(id: "{work item uuid}")
-```
-
-Use it for **forward progression**, one status at a time, as each step's work actually finishes — how progression differs by pipeline and item type is in §5.
-
-### When NOT to use
-
-- Don't use to skip statuses (e.g., backlog → done)
-- Don't use to go backward — there is no `work_status_prev`
-- Don't call repeatedly to "fast forward" through multiple statuses without doing the actual work
-
----
-
-## 3. How `work_status_done` Works
-
-`work_status_done` moves a work item directly to the "done" status, regardless of its current position.
-
-### Resolution logic
-
-1. Looks for a status mapped to a column with `is_done_column = true`
-2. Fallback: picks the first status with `category === "done"`
-3. Sets `completed_at = now()` on the work item
-
-### When to use
-
-```
-work_status_done(id: "{work item uuid}")
-```
-
-Use this when work is **fully complete and verified**:
-- All acceptance criteria are met
-- Tests pass
-- Review is approved (if applicable)
-
-<HARD-GATE>
-Do NOT call work_status_done unless the work is genuinely complete.
-"Almost done" is not done. "Tests are mostly passing" is not done.
-Verify all acceptance criteria before marking an item as done.
-</HARD-GATE>
-
----
-
-## 3.1 Where an agent's authority ends
-
-> **An agent drives everything that is verification. It stops at the first gate that changes
-> the world outside the repository.**
-
-Deploying does that. Verifying does not. The rule survives renaming because it describes what
-a gate *is*, not what it is called — which is the only kind of rule that works when every
-team configures its own statuses.
-
-In practice, on the seeded presets: reviewing, scanning, testing, and updating docs are all
-verification and all satisfiable by an agent. Every deploy stage, and any validation
-performed in a deployed environment, is not.
-
-<HARD-GATE>
-`work_status_done` is **not** the exit from a pipeline an agent cannot finish. Calling it
-from four statuses away records "done" for work that never passed the gates in between.
-
-Use it only when the item's next status **is** the done status. Otherwise stop at the last
-gate you satisfied and say plainly which gate is next and who owns it.
-</HARD-GATE>
-
-An unrecognised status is treated as a stop, not a pass. Ask once who satisfies it, record
-the answer in the team's delivery configuration, and never ask again.
-
----
-
-## 4. Checking Available Statuses
-
-Before moving items, understand what statuses exist:
-
-### List all statuses
-
-```
-work_statuses()
-```
-
-Returns all available statuses with their categories and names.
-
-### View board columns
-
-```
-board_columns()
-```
-
-Returns the board's columns for the given `board_id` — each rendered as `- {column name} (ID: {column id})`. Note: this tool's text output does not surface which statuses map to which column, nor an explicit ordering field (`boards.py`'s `board_columns` action only formats `name` and `id` per column) — that richer structure may exist in the underlying API but isn't exposed here. Use it to confirm which columns exist on a board; pair it with `work_statuses()` for status names/categories.
-
----
-
-## 5. Progression Patterns by Item Type
-
-Progression differs by pipeline, not only by type. **Epics and features live on the `product`
-pipeline; stories, bugs, hotfixes, tasks, spikes, and subtasks live on `engineering`.** A
-cascade from task to epic therefore crosses pipelines, and the statuses available on each side
-are different sets.
-
-What holds regardless of the team's configuration:
-
-- **Parents move because children moved.** A story advances when its tasks do; a feature when
-  its stories do; an epic when its features do. Never the other way round.
-- **A parent never reaches the done category while any child is outside it.** This is the one
-  rule that failed in practice: a story closed with seven of fifteen tasks still mid-pipeline,
-  because closing it was the only exit the flow offered. Stopping is the exit.
-- **The Executor advances a task only to the first review gate.** The move past that is the
-  Orchestrator's, after review clears — see `orchestrator` §6.
-
----
-
-## 6. Common Mistakes
-
-| Mistake | Why it's wrong | Do this instead |
-|---------|---------------|-----------------|
-| Moving story to done before all tasks are done | Misrepresents progress | Check `work_children` first — all tasks must be done |
-| Marking a task done as soon as its own tests pass | Done requires review approval, not just green tests | `work_status_next` once, to the first review gate, and stop; the Orchestrator carries it from there — see §3.1 |
-| Skipping statuses with repeated `work_status_next` | Loses tracking fidelity | Only advance when the work for that status is actually complete |
-| Moving to in_progress without planning | No tasks = no accountability | Run Technical Planning first, create tasks, then advance |
-| Forgetting to check board structure | Different teams may have different progressions | Always check `board_columns` if unsure about available statuses |
-| Moving a cancelled item to done | Contradictory | Cancelled items stay cancelled |

package/skills/branch-landing/SKILL.md

@@ -1,88 +0,0 @@
----
-name: branch-landing
-description: Decide and execute what happens to a branch once its work is done — merge, open a pull request, or leave it — then tear down the worktree and pane without losing anything. Use when a story's implementation is complete, or when another skill needs the teardown sequence.
-version: "1.0"
-category: methodology
----
-
-# Branch Landing
-
-Code that is written and reviewed is not yet delivered. It sits on a branch, and something has to decide what happens to it. This skill is that decision and the sequence that carries it out.
-
-## 1. A branch does not land ahead of its story
-
-<HARD-GATE>
-Before anything else, check where the story actually is.
-
-If the story is parked at a pipeline gate — waiting on QA, a scan, a deploy, anything the team satisfies outside this session (see `board-progression` §3.1) — **the branch waits with it.** Do not merge, do not open a pull request, do not remove the worktree.
-
-Landing code whose story never passed its gates is the same defect as closing a story to tidy the board, one layer down. Say which gate the story waits at, and stop.
-</HARD-GATE>
-
-The work item is the authority on whether the work is done. The branch follows it; it never leads.
-
-## 2. Ask how the work should land
-
-Teams integrate differently and the plugin has no basis to guess. Ask once, with a recommendation so accepting takes a word:
-
-| Option | What happens | When it fits |
-|---|---|---|
-| **Pull request** | Push the branch, open a PR against the base, leave everything standing | Any team that reviews before merging, or where CI runs on the PR |
-| **Merge locally** | Merge into the base in the main checkout, then tear down | Solo work, or a change already reviewed by the two axes |
-| **Leave it** | Push for safety, change nothing else | The human wants to look first, or the work is paused |
-
-The base branch is per-repo and comes from the `Allye Delivery Configuration` Core Document — **never assumed.** Repos with a git-flow layout branch from `develop`; repos releasing from trunk branch from `main`.
-
-**Nothing merges into the base branch without the human choosing it in this conversation.** A merge is not reversible in the way an unmerged branch is, and no amount of green review substitutes for being asked.
-
-## 3. The sequence, when merging locally
-
-Every step is a gate. One story at a time; do not batch.
-
-```
-1. GATE:  git -C <worktree> status --porcelain   must be EMPTY
-          dirty → STOP, escalate. Do not merge, do not remove.
-2. git push -u origin <branch>
-3. In the MAIN checkout, on the base:  git merge --no-ff <branch>
-4. Conflicts in shared wiring files are expected when parallel work
-   touched the same composition root. Resolve by CONSOLIDATING into one
-   instance — never by picking a side.
-5. Rebuild, typecheck, run tests BEFORE committing the merge
-6. git worktree remove <path>          ← without --force
-7. Close the runtime pane              ← only after step 6
-```
-
-### The three locks
-
-Each exists because it prevents one specific way work disappears. They look skippable right up until they are not.
-
-| Lock | What it prevents |
-|---|---|
-| **Push before removal** (2) | The branch exists on the remote before anything is destroyed. After this, no local accident loses the work. |
-| **`worktree remove` without `--force`** (6) | Git refuses a dirty worktree. That refusal is the last safety net; bypassing it by reflex is how uncommitted work vanishes. |
-| **Pane closes last** (7) | While the pane lives, the session's reasoning is inspectable. Close it before a validated merge and the *why* is gone, even though the *what* survives in the diff. |
-
-### When merging is not the choice
-
-**Pull request:** push, open the PR against the base, and stop. Worktree and pane stay — review feedback arrives there. Record the PR reference on the story so the next session finds it.
-
-**Leave it:** push, and change nothing else. Say plainly what is standing: branch, worktree, pane.
-
-## 4. Never
-
-- **Never merge into the base branch unasked.** §2.
-- **Never force-push.** A force-push rewrites what step 2 exists to protect.
-- **Never delete a branch.** Merged branches are cheap and are the record of how something was built. Removing a worktree is not deleting its branch, and should not become it.
-- **Never destroy what you did not create.** A worktree or pane that predates this session belongs to someone else.
-
-## 5. Abandoned work
-
-A story that failed, was cancelled, or stalled gets **no cleanup at all**. Worktree, branch, and pane all stay.
-
-Visible litter costs far less than deleted work, and an abandoned branch is often the only record of an approach that was tried and rejected — which is worth more than the disk it occupies.
-
-## 6. Record where it landed
-
-Once the work has landed, the branch may be the only durable trace outside the diff. Carry the reference into the delivery memory (`memory_save`, `sector: "knowledge"`): the branch name, the merge commit or PR reference, and the base it landed on.
-
-A memory that says a story was delivered, without saying where the code went, is a memory that sends the next reader searching.

package/skills/delivery/SKILL.md

@@ -1,187 +0,0 @@
----
-name: delivery
-description: Workflow for finalizing a story after all tasks pass review. Verifies completeness, closes the story, updates documentation, and cleans up. Use when all tasks are done and reviewed.
-version: "1.4"
-category: methodology
----
-
-# Technical Delivery Workflow
-
-This skill finalizes a story after every task has passed review — closing it out, documenting what shipped, and clearing loose ends.
-
-Use this when: all tasks for a story are implemented and reviewed, and the user is ready to finalize delivery.
-
----
-
-## Workflow Overview
-
-```
-Verify all tasks done → Close story → Update documentation → Clean up TODOs → Save delivery memory
-```
-
----
-
-## Step 1: Verify All Tasks Are Complete
-
-Check that every task under the story is done:
-
-```
-work_children(id: "{story uuid}")
-```
-
-<HARD-GATE>
-Close the story only once every task is completed, verified, and in "done" status.
-If any task is incomplete, route back to Technical Development or Technical Review instead of closing.
-
-"Done" means the **done category**, not the last status an agent could reach. On a pipeline
-with stages after review, a task parked at a gate the team satisfies by hand is not done — it
-is waiting, and the story waits with it.
-
-If tasks are parked, close-out is not blocked by an oversight. It is **not yet due**. Say which
-gate they are waiting at and stop; do not close the story to tidy the board.
-</HARD-GATE>
-
-### Verification checklist
-
-For each task, confirm:
-- [ ] Status is "done"
-- [ ] Acceptance criteria are met
-- [ ] Tests pass
-- [ ] Review is approved (no outstanding change requests)
-
----
-
-## Step 2: Close the Story
-
-Move the story to done:
-
-```
-work_status_done(id: "{story uuid}")
-```
-
-This sets the story's status to the "done" category and records `completed_at`.
-
-If the story is part of a feature, check if the feature is now complete:
-
-```
-work_children(id: "{feature uuid}")
-```
-
-If all stories under the feature are done, close the feature too:
-
-```
-work_status_done(id: "{feature uuid}")
-```
-
----
-
-## Step 2.5: Land the Code
-
-The story is closed in Allye. The code is still on a branch.
-
-Load the `branch-landing` skill and follow it. It asks how the work should land — pull
-request, local merge, or left alone — and carries the sequence that gets it there without
-losing anything.
-
-<HARD-GATE>
-Do not skip this because the story is already closed. Closing the item and landing the code
-are different acts, and doing the first without the second produces the worst available
-state: a board that says delivered and a base branch that does not have the work.
-
-If the story reached this skill while still parked at a pipeline gate, it should not have —
-see Step 1. The branch stays where it is.
-</HARD-GATE>
-
----
-
-## Step 3: Update Documentation
-
-If the delivered work introduced or changed functionality that should be documented:
-
-### Check existing docs
-
-```
-memory_search(query: "documentation {feature/story key}")
-doc_full_tree()
-```
-
-### Create or update documentation
-
-**For new functionality:**
-
-```
-doc_create(
-  doc_title: "{Feature Name}",
-  doc_type: "page",
-  doc_emoji: "📄",
-  doc_content: "## Overview\n{what this feature does}\n\n## Usage\n{how to use it}\n\n## Technical Details\n{relevant implementation details}\n\n## API Reference\n{endpoints, parameters, responses — if applicable}",
-  doc_parent_id: "{parent folder uuid if applicable}"
-)
-```
-
-**For updates to existing functionality:**
-
-```
-doc_update(
-  id: "{doc uuid}",
-  doc_content: "{updated content}"
-)
-```
-
-### When to skip documentation
-
-Not everything needs docs. Skip if:
-- The change is purely internal (refactoring, performance, tests)
-- The change is self-evident from the code
-- Documentation would duplicate what's in the code
-
----
-
-## Step 4: Clean Up TODOs
-
-Check for any TODOs that were created during development:
-
-```
-todo_list()
-```
-
-For each TODO related to this story:
-- If it's done → mark as complete: `todo_update(id: "{todo uuid}", status: "completed")`
-- If it's no longer relevant → delete: `todo_delete(id: "{todo uuid}")`
-- If it's a future task → leave it, but make sure it's not blocking delivery
-
----
-
-## Step 5: Save Delivery Memory
-
-Save a final summary of what was delivered:
-
-```
-memory_save(
-  title: "Delivered — {STORY-KEY} {story title}",
-  content: "## What was delivered\n{summary of the feature/change}\n\n## Tasks completed\n- {TASK-1}: {title}\n- {TASK-2}: {title}\n- {TASK-3}: {title}\n\n## Key decisions\n{important decisions from planning and implementation}\n\n## Documentation\n{what was documented, or 'No documentation needed'}\n\n## Where the code landed\n{branch name, and the merge commit or PR reference, and the base it landed on — or \"not yet landed: {reason}\"}\n\n## Lessons learned\n{anything worth remembering for similar work in the future}",
-  tags: ["delivery", "completed", "{story-key}", "{feature-key}"],
-  sector: "knowledge"
-)
-```
-
----
-
-## Workflow Checklist
-
-- [ ] All tasks verified as done
-- [ ] Story moved to done
-- [ ] The code landed, or the reason it has not is recorded
-- [ ] Feature moved to done (if all stories complete)
-- [ ] Documentation created or updated (if applicable)
-- [ ] Related TODOs cleaned up
-- [ ] Delivery memory saved
-
----
-
-## What Comes Next
-
-The story is delivered. The user can:
-- **Pick another story** → Back to Technical Planning (`allye-technical-planning`)
-- **Plan more features** → Back to Product Planning (`allye-product-planning`)
-- **Start a new initiative** → Back to Product Planning from scratch