@loopflowhq/agent-pack 0.3.0 → 0.5.0

package/.cursor/commands/lfq-get-ticket-context.md

@@ -0,0 +1,4 @@
+# lfq-get-ticket-context — Get ticket context
+
+Follow `loopflowhq/commands/get-ticket-context.md`.
+

package/.cursor/commands/lfq-next-best-action.md

@@ -0,0 +1,3 @@
+# lfq-next-best-action — Next best action
+
+Follow `loopflowhq/commands/next-best-action.md`.

package/.cursor/commands/lfq-start-next-best-action.md

@@ -0,0 +1,4 @@
+# lfq-start-next-best-action — Start next best action
+
+Follow `loopflowhq/commands/start-next-best-action.md`.
+

package/.cursor/commands/lfq-start-next-phase.md

@@ -0,0 +1,4 @@
+# lfq-start-next-phase — Start next phase
+
+Follow `loopflowhq/commands/start-next-phase.md`.
+

package/loopflowhq/README.md

@@ -4,10 +4,8 @@ The canonical, prompt-ready workflow description for agents lives in `loopflowhq
 
 Phase playbooks:
 
-- `loopflowhq/phases/define.md`
-- `loopflowhq/phases/discovery.md`
-- `loopflowhq/phases/refine.md`
-- `loopflowhq/phases/plan.md`
-- `loopflowhq/phases/implement.md`
-- `loopflowhq/phases/review.md`
-- `loopflowhq/phases/close.md`
+- Ticket type + phase files follow this pattern:
+  - `loopflowhq/phases/<ticket_type>-<phase>.md`
+  - where `<ticket_type>` is one of: `epic`, `story`, `task`, `followup`
+
+Routing lives in `loopflowhq/agent.md`.

package/loopflowhq/agent.md

@@ -22,10 +22,6 @@ This file is the canonical, repo-local description of how LoopFlowHQ work. It is
 
 - `phase`: typed workflow phase (what kind of work is happening)
 - `phase_state`: progress within a phase
-- Legacy fields exist for compatibility:
-  - `status` / `substate` (older workflow model)
-
-Typed workflow is the canonical model; legacy fields may still be updated for backward compatibility.
 
 ## Canonical typed workflow
 
@@ -40,18 +36,32 @@ Typed workflow is the canonical model; legacy fields may still be updated for ba
 
 - Epic: `discovery` -> `refine` -> `plan` -> `implement` -> `close`
 - Story: `plan` -> `implement` -> `review` -> `close`
-- Task: `define` -> `implement`
+- Task: `define` -> `implement` -> `close`
 - Followup: `review` -> `close`
 
-See phase playbooks:
-
-- `loopflowhq/phases/define.md`
-- `loopflowhq/phases/discovery.md`
-- `loopflowhq/phases/refine.md`
-- `loopflowhq/phases/plan.md`
-- `loopflowhq/phases/implement.md`
-- `loopflowhq/phases/review.md`
-- `loopflowhq/phases/close.md`
+See phase playbooks (ticket_type routed):
+
+- Pattern: `loopflowhq/phases/<ticket_type>-<phase>.md`
+- Ticket types: `epic`, `story`, `task`, `followup`
+- Routing table:
+  - Epic:
+    - discovery: `loopflowhq/phases/epic-discovery.md`
+    - refine: `loopflowhq/phases/epic-refine.md`
+    - plan: `loopflowhq/phases/epic-plan.md`
+    - implement: `loopflowhq/phases/epic-implement.md`
+    - close: `loopflowhq/phases/epic-close.md`
+  - Story:
+    - plan: `loopflowhq/phases/story-plan.md`
+    - implement: `loopflowhq/phases/story-implement.md`
+    - review: `loopflowhq/phases/story-review.md`
+    - close: `loopflowhq/phases/story-close.md`
+  - Task:
+    - define: `loopflowhq/phases/task-define.md`
+    - implement: `loopflowhq/phases/task-implement.md`
+    - close: `loopflowhq/phases/task-close.md`
+  - Followup:
+    - review: `loopflowhq/phases/followup-review.md`
+    - close: `loopflowhq/phases/followup-close.md`
 
 ## Transition rules (typed workflow)
 
@@ -59,6 +69,11 @@ Within a phase, the normal progression is:
 
 - `ready` -> `in_progress` -> `done`
 
+Agents should explicitly move the ticket as work starts and ends:
+
+- At the beginning of phase execution: set `phase_state=in_progress`
+- At the end of phase execution: set `phase_state=done`
+
 When feedback fails a gate in the current phase:
 
 - `in_progress` -> `changes_requested` (or directly set `changes_requested`)
@@ -68,20 +83,61 @@ Moving to the next phase:
 
 - When a phase is `done`, the next phase starts at `ready`.
 
-If you are an agent with tool access, prefer to ask LoopFlowHQ for the next move instead of guessing:
+Story autonomy expectation:
+
+- In `story` Implement, a coding agent should be able to complete the work without further human input (based on the approved plan + acceptance criteria), then move the ticket to `phase=review`, `phase_state=ready` and post the PR link in ticket chat.
+
+## Required ticket context (before doing work)
+
+Before doing ticket work in any phase, load the ticket context from LoopFlowHQ so work stays aligned with the source of truth:
+
+- Prefer a single call: `get_ticket_context` (title, description, acceptance criteria, chat history, subtasks)
+- If needed, fetch separately:
+  - Ticket details: `get_ticket`
+  - Ticket chat history: `get_ticket_messages`
+  - Ticket subtasks: `get_ticket_subtasks`
 
-- Call `next_best_action` and apply the returned `{ phase, phase_state }` as the next transition.
+Do this in order:
+
+1. Via MCP tools (if available).
+2. Via the LoopFlowHQ Actions REST API (if available).
+3. If tool access is not available, ask the human to paste the ticket title/description/acceptance criteria and any relevant recent messages.
 
 ## How to talk to LoopFlowHQ (tools)
 
 If MCP / Actions tools are available, the standard loop is:
 
 1. `get_ticket` (+ `get_ticket_messages`) to load context.
-2. `next_best_action` to confirm the recommended transition.
-3. `update_ticket` (preferred) to set `phase` / `phase_state` as you start and finish a step.
-4. `post_ticket_message` to write a concise step summary (what changed, what was decided, what is next).
+2. `update_ticket` to set `phase` / `phase_state` as you start and finish a step.
+3. `post_ticket_message` to write a concise step summary (what changed, what was decided, what is next).
+
+## "Start/Execute" intent (kick off a conversation)
+
+When the user's intent is to **start / execute / do** work (not just inspect), for example:
+
+- "start next phase"
+- "start next-best-action"
+- "start next phase of ticket LOOPF-123"
+- synonyms: "execute", "start", "do"
+
+Then **do not only move workflow state**. Also **start a conversation immediately** in the ticket chat.
+
+Required behavior (when tools are available):
+
+1. Move the ticket into the correct working state:
+   - If the user is starting the next phase for a specific ticket:
+     - compute the transition deterministically from the typed workflow (ticket type + current `phase`/`phase_state`)
+     - do not use `next_best_action` for this case
+   - If the user intent is "next best action" (especially when no ticket is specified and a ticket must be selected):
+     - call `next_best_action` to select the ticket and recommended next workflow step
+   - set `phase_state=in_progress` for the phase you are starting (use `update_ticket` or `update_ticket_status` depending on your tool surface)
+2. Post a kickoff message via `post_ticket_message` that includes:
+   - what you changed (from -> to `phase/phase_state`)
+   - what you will do next (1-3 bullets)
+   - what you need from the human (3-7 concrete questions, with defaults if possible)
+3. Optional (recommended when you need structured answers): also call `post_ticket_agent_questions` with the same questions.
 
-Legacy-only clients may instead use `update_ticket_status` with `status` / `substate`, but typed workflow is preferred whenever available.
+Fallback (no tool access): draft the kickoff message and ask the user to paste it into the ticket chat.
 
 ## API-first ticket operations (deterministic)
 
@@ -97,8 +153,7 @@ Common actions:
 - Read: `POST /get_ticket`
 - Messages: `POST /get_ticket_messages`
 - Create: `POST /create_ticket`
-- Update fields (preferred): `POST /update_ticket`
-- Legacy status/substate (fallback): `POST /update_ticket_status`
+- Update fields: `POST /update_ticket`
 - Post message: `POST /post_ticket_message`
 - Post agent questions: `POST /post_ticket_agent_questions`
 

package/loopflowhq/commands/get-ticket-context.md

@@ -0,0 +1,25 @@
+# Command: Get Ticket Context
+
+Goal: load the ticket context needed to implement safely.
+
+## Steps
+
+1. Ensure you have a ticket key/ID. If none is available, ask the user which ticket to use.
+2. Call `get_ticket_context({ ticket, messages_limit })`.
+3. Use the returned fields as the source of truth for implementation:
+   - `title`
+   - `description`
+   - `acceptance_criteria`
+   - `chat_history`
+   - `subtasks`
+
+## Output format
+
+```
+## Ticket context
+- Ticket: <KEY or id> — <title>
+- Acceptance criteria: <present|missing>
+- Subtasks: <count>
+- Messages: <count>
+```
+

package/loopflowhq/commands/next-best-action.md

@@ -0,0 +1,36 @@
+# Command: Next Best Action
+
+Goal: determine the recommended next workflow transition for a ticket (or pick the next ticket to work on).
+
+If the user intent is to **start/execute** the work (not just inspect), use:
+
+- `loopflowhq/commands/start-next-best-action.md`
+
+## Steps
+
+1. Determine the **requester type** (who is asking for next best action):
+   - `human`: a human in the LoopFlowHQ UI/app
+   - `chat agent`: a discussion LLM (e.g. ChatGPT/Claude/Gemini)
+   - `code agent`: a coding agent (e.g. Codex/Cursor/Claude Code)
+2. Ensure you have a ticket key/ID. If none is available, ask the user which ticket to use.
+3. Call `next_best_action`.
+   - If a ticket is provided: `next_best_action({ ticket })`
+   - If no ticket is provided: `next_best_action({ limit })`
+4. If a ticket was selected, call `get_ticket({ ticket })` so you can report its `type` (e.g. epic/story/task/followup).
+5. Report:
+   - requester type (`human|chat agent|code agent`)
+   - selected ticket (id/key/title when present)
+   - selected ticket type (epic/story/task/followup when available; otherwise the raw `ticket.type`)
+   - current `{ phase, phase_state }`
+   - next `{ phase, phase_state }` (or null)
+
+## Output format
+
+```
+## Next best action
+- Requester: <human|chat agent|code agent>
+- Ticket: <KEY or id> — <title>
+- Ticket type: <epic|story|task|followup|...> (or "unknown")
+- Current: <phase>/<phase_state>
+- Next: <phase>/<phase_state> (or "none")
+```

package/loopflowhq/commands/start-next-best-action.md

@@ -0,0 +1,53 @@
+# Command: Start Next Best Action
+
+Goal: pick the next ticket (if none is provided), start the recommended workflow step, and immediately kick off a conversation in the ticket chat.
+
+This command is for user intents like:
+
+- "start next-best-action"
+- "execute next best action"
+- "do the next best action"
+
+## Steps
+
+1. Determine requester type:
+   - `human`: a human in the LoopFlowHQ UI/app
+   - `chat agent`: a discussion LLM (e.g. ChatGPT/Claude/Gemini)
+   - `code agent`: a coding agent (e.g. Codex/Cursor/Claude Code)
+2. Call `next_best_action`.
+   - If a ticket is provided: `next_best_action({ ticket })`
+   - If no ticket is provided: `next_best_action({ limit })`
+3. If `next` is null: report "none" and stop (do not invent work).
+4. Load ticket context:
+   - `get_ticket({ ticket })` for type/title
+   - `get_ticket_context({ ticket, messages_limit })` if you need context before asking questions
+5. Start the work (move workflow state):
+   - Determine the target phase/state:
+     - If `next.phase_state` is `in_progress`: use it as-is.
+     - If `next.phase_state` is `ready`: set target to `{ phase: next.phase, phase_state: in_progress }` (start the phase).
+     - If `next.phase_state` is `done`: do **not** apply it for a "start" intent; ask for confirmation.
+   - Update the ticket (one call):
+     - Prefer `update_ticket({ ticket, phase, phase_state })`
+     - If you must use `update_ticket_status`, set `status` consistent with the target phase (legacy mapping):
+       - discovery -> discovery
+       - refine/plan -> planning
+       - implement -> in_progress
+       - review/close -> review (close done becomes done)
+6. Kick off the conversation immediately:
+   - Call `post_ticket_message({ ticket, content })` with:
+     - the transition you applied (`from` -> `to`)
+     - what you will do next (1-3 bullets)
+     - 3-7 concrete questions (with default assumptions)
+   - Optional (recommended): also call `post_ticket_agent_questions` with the same questions.
+
+## Output format
+
+```
+## Started next best action
+- Requester: <human|chat agent|code agent>
+- Ticket: <KEY or id> — <title>
+- Ticket type: <epic|story|task|followup|...>
+- Transition: <from phase/state> -> <to phase/state>
+- Kickoff: posted to ticket chat (message + optional structured questions)
+```
+

package/loopflowhq/commands/start-next-phase.md

@@ -0,0 +1,49 @@
+# Command: Start Next Phase (for a ticket)
+
+Goal: for a specific ticket, start the next phase of work and immediately kick off a conversation in the ticket chat.
+
+This command is for user intents like:
+
+- "start next phase"
+- "start next phase of ticket LOOPF-123"
+- "execute the next phase"
+
+## Steps
+
+1. Ensure you have a ticket key/ID. If none is available, ask the user which ticket to use.
+2. Load the ticket's current typed workflow state:
+   - Call `get_ticket({ ticket })` (or `get_ticket_context({ ticket })`) and read `{ type, phase, phase_state }`.
+   - Do **not** call `next_best_action` when the user is already talking about a specific ticket and the intent is "start next phase".
+     - Reserve `next_best_action` for "next best action" intents, especially when no ticket is specified and you need to select work.
+3. Decide what "start" means (non-destructive defaults):
+   - If `current.phase_state` is `ready`: start the current phase (`phase_state=in_progress`).
+   - If `current.phase_state` is `changes_requested`: start rework in the same phase (`phase_state=in_progress`).
+   - If `current.phase_state` is `done`: start the next phase (`phase_state=in_progress`) by advancing deterministically using the typed workflow for the ticket type:
+     - Epic: `discovery` -> `refine` -> `plan` -> `implement` -> `close`
+     - Story: `plan` -> `implement` -> `review` -> `close`
+     - Task: `define` -> `implement` -> `close`
+     - Followup: `review` -> `close`
+     - If the current phase is already the last phase for the ticket type, do not advance; post a kickoff message and ask what the user wants next.
+   - If `current.phase_state` is `in_progress`: do not mark done; post a kickoff message anyway and ask what to do next.
+4. Update the ticket to the target `{ phase, phase_state }`:
+   - Prefer `update_ticket({ ticket, phase, phase_state })`.
+   - If using `update_ticket_status`, choose a legacy `status` consistent with the target phase:
+     - discovery -> discovery
+     - refine/plan -> planning
+     - implement -> in_progress
+     - review/close -> review (close done becomes done)
+5. Kick off the conversation immediately:
+   - Call `post_ticket_message({ ticket, content })` with:
+     - the transition you applied (`from` -> `to`)
+     - what you will do next (1-3 bullets)
+     - 3-7 concrete questions (with default assumptions)
+   - Optional (recommended): also call `post_ticket_agent_questions` with the same questions.
+
+## Output format
+
+```
+## Started next phase
+- Ticket: <KEY or id> — <title>
+- Transition: <from phase/state> -> <to phase/state>
+- Kickoff: posted to ticket chat (message + optional structured questions)
+```

package/loopflowhq/phases/epic-close.md

@@ -0,0 +1,25 @@
+# Ticket Type: Epic - Phase: Close
+
+Goal: close the epic by confirming the outcome, capturing what shipped and verification evidence, and creating followups when needed.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Approved outcome (or explicit cancellation reason)
+- Any rollout/release constraints
+
+## Outputs (minimum)
+
+- "What shipped" summary
+- Verification steps (and results)
+- Followups created if needed (or explicitly skipped)
+
+## Agent checklist
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Ensure the epic summary matches what actually changed.
+- If cancelled, record why and whether a followup is needed.
+- Prefer small cleanup over "nice-to-have" refactors.
+- Run verification (lint/build/test/manual) appropriate to the change before closing.
+- Post a final Close summary in the ticket chat (`post_ticket_message`).
+

package/loopflowhq/phases/{discovery.md → epic-discovery.md}

@@ -1,21 +1,25 @@
-# Phase: Discovery
+# Ticket Type: Epic - Phase: Discovery
 
 Goal: explore scope and reduce uncertainty before committing to a solution.
 
 ## Inputs
 
-- Problem statement and constraints
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Initial problem statement and constraints
 - Existing system context (code, docs, prior tickets)
 
 ## Outputs (minimum)
 
 - Clarified requirements and edge cases
+- Open questions (only the ones that block progress)
 - Proposed approach options (if needed) with tradeoffs
-- A narrowed, agreed scope
+- A narrowed scope ready for Refine/Plan
+- Discovery summary captured in the ticket chat (via `post_ticket_message`)
 
 ## Agent checklist
 
+- Load ticket context (see `loopflowhq/agent.md`).
+- Ask clarification questions in this chat, one at a time; wait for answers before asking the next.
 - Identify what is unknown and what must be decided by a human.
 - Validate assumptions against the codebase when possible.
 - If requirements are missing, ask targeted questions instead of guessing.
-

package/loopflowhq/phases/epic-implement.md

@@ -0,0 +1,26 @@
+# Ticket Type: Epic - Phase: Implement
+
+Goal: deliver the epic's acceptance criteria by executing the approved plan (typically via child Stories), with tests and minimal risk.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Approved plan (story breakdown + sequencing)
+
+## Outputs (minimum)
+
+- Planned child stories progressed through implement/review/close
+- Epic `phase_state` reflects overall progress (`ready` / `in_progress` / `done`)
+- Verification evidence captured for anything that shipped (commands run, expected outputs)
+
+## Agent checklist
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Confirm the epic has an approved plan; if missing or stale, send it back to Epic Plan.
+- Prefer executing work via child Stories:
+  - Identify the next child Story from the epic plan / linked stories.
+  - Start that Story's Implement phase and work it through Review and Close per the Story playbooks.
+- If there are epic-level tasks that must be executed directly, follow the same standards as Story/Task:
+  - small diffs, tests, and `npm run lint` / `npm run test` / `npm run build` as applicable.
+- Keep the epic's `phase_state` in sync with overall progress.
+

package/loopflowhq/phases/{plan.md → epic-plan.md}

@@ -1,9 +1,10 @@
-# Phase: Plan
+# Ticket Type: Epic - Phase: Plan
 
 Goal: decide the smallest safe implementation plan with verification.
 
 ## Inputs
 
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
 - Final requirements + acceptance criteria
 - System constraints (tech stack, performance, security, rollout)
 
@@ -12,10 +13,14 @@ Goal: decide the smallest safe implementation plan with verification.
 - Step-by-step plan (small diffs)
 - Verification steps (tests/lint/build/manual steps)
 - Risks and rollback plan (if needed)
+- Story breakdown (sequenced, deployable chunks with clear acceptance criteria)
+- Plan stored in the ticket description (as a `## Plan` section)
 
 ## Agent checklist
 
+- Load ticket context (see `loopflowhq/agent.md`).
 - Keep the plan minimal and aligned with current project patterns.
 - Identify where human approval is needed (review gates, product decisions).
 - Prefer “prove it” steps (tests, screenshots, logs) over promises.
-
+- Do not implement in this phase; produce the plan as the deliverable.
+- Do not change repo files in this phase.

package/loopflowhq/phases/{refine.md → epic-refine.md}

@@ -1,9 +1,10 @@
-# Phase: Refine
+# Ticket Type: Epic - Phase: Refine
 
 Goal: turn discovery output into a precise, buildable specification.
 
 ## Inputs
 
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
 - Discovery notes and decisions
 - Existing constraints (time, architecture, UX expectations)
 
@@ -12,10 +13,14 @@ Goal: turn discovery output into a precise, buildable specification.
 - Finalized acceptance criteria
 - Non-goals and explicit exclusions
 - Implementation shape (high-level architecture, key files/modules)
+- Risks / rollout notes (if applicable)
+ - Story list / execution shape (what will be delivered and in what chunks)
+ - Refine summary captured in the ticket chat (via `post_ticket_message`)
 
 ## Agent checklist
 
+- Load ticket context (see `loopflowhq/agent.md`).
 - Ensure acceptance criteria is testable and unambiguous.
 - Surface any scope creep since Discovery and ask for confirmation.
 - Call out any “this changes behavior” items explicitly.
-
+- If you change the spec/AC, update the ticket to reflect the new source of truth.

package/loopflowhq/phases/followup-close.md

@@ -0,0 +1,21 @@
+# Ticket Type: Followup - Phase: Close
+
+Goal: close the loop: summarize the outcome and leave the system clean.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Approved outcome (or explicit cancellation reason)
+
+## Outputs (minimum)
+
+- "What changed" / "What was decided" summary in ticket chat
+- Followups created if needed
+
+## Agent checklist
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Ensure the ticket summary matches what actually happened.
+- If cancelled, record why and whether a followup is needed.
+- Prefer small cleanup over "nice-to-have" refactors.
+

package/loopflowhq/phases/followup-review.md

@@ -0,0 +1,25 @@
+# Ticket Type: Followup - Phase: Review
+
+Goal: validate the followup outcome and decide whether it is acceptable as-is.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Implemented change (if any) and the reported outcome
+- Any acceptance criteria (if present)
+
+## Outputs (minimum)
+
+- Review notes captured in ticket chat
+- One of:
+  - Approved: set `phase=review`, `phase_state=done`, then move to Close (`phase=close`, `phase_state=ready`)
+  - Changes requested: set `phase=review`, `phase_state=changes_requested` with an actionable list of fixes
+
+## Agent checklist
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Prioritize correctness and regressions over style.
+- Ensure acceptance criteria (if present) is demonstrably met.
+- Post a single consolidated list of requested changes if not approved.
+- Do not mark human-owned gates complete unless explicitly instructed by the human owner.
+

package/loopflowhq/phases/shared-close-checklist.md

@@ -0,0 +1,15 @@
+# Shared: Close Checklist (Story/Task)
+
+Use this checklist to avoid duplicating close/shipping guidance across Story/Task phases.
+
+## Checklist items to cover
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Confirm you have the PR link and checks are green.
+- Merge and ship:
+  - merge the PR to `main` automatically when checks pass
+  - if the project uses a different ship mechanism than “merge to main” (merge queue, release-please, manual promote, etc.), follow the repo’s standard process and run it instead
+  - if merge/deploy is blocked by missing permissions, post exact instructions and the PR link in ticket chat so a human can perform the single action
+- Post a concise “what shipped” summary in ticket chat (include PR link and any deploy evidence).
+- Ensure the ticket summary matches what actually changed.
+- Create followups if needed (bugs, tech debt, missing tests, rollout tasks).

package/loopflowhq/phases/shared-execution-checklist.md

@@ -0,0 +1,33 @@
+# Shared: Execution Checklist (Story/Task)
+
+Use this checklist to avoid duplicating execution guidance across Story/Task phases.
+
+## Requirements
+
+- Each subtask should be small and independently committable.
+- Prefer 1 subtask = 1 commit (or a small sequence of commits) so work can be reviewed and reverted safely.
+- Before each commit, run the standard checks (or the closest equivalents for the repo):
+  - `npm run lint`
+  - `npm run test`
+  - `npm run build`
+- If the change includes UI:
+  - include explicit subtasks to verify light mode and dark mode
+  - include explicit subtasks to verify desktop and mobile layouts
+- UX/UI rules are project-specific:
+  - follow the current repo's UX/UI spec and components; do not invent a new design system
+- Reuse existing components and patterns; do not duplicate functionality unless there is a clear reason.
+- Do a self code review before each commit (review diff for correctness, edge cases, a11y, and unintended behavior changes).
+- When implementation is complete, move the ticket forward in the typed workflow:
+  - Story Implement -> `phase=review`, `phase_state=ready` (post PR link)
+  - Task Implement -> `phase=close`, `phase_state=ready` (post summary / PR link if used)
+
+## Checklist items to cover
+
+- Implement code (small diffs)
+- Implement UI per project UX/UI rules (states: loading/empty/error; copy; a11y; responsiveness)
+- Write tests (unit/integration/e2e as appropriate)
+- Run tests and regression checks
+- Ensure `npm run lint`, `npm run build`, `npm run test` pass
+- Call out any behavior changes and migrations (and any follow-ups)
+- Update project docs (architecture/feature docs) when warranted
+- Create/update ADRs when warranted

package/loopflowhq/phases/shared-planning-checklist.md

@@ -0,0 +1,17 @@
+# Shared: Planning Checklist (Story/Task)
+
+Use this checklist to avoid duplicating planning and refinement guidance across phases.
+
+## Checklist items to cover
+
+- Scan the codebase/docs first to confirm whether the work is already partially or fully implemented.
+- Rewrite the ticket to be implementation-ready:
+  - title: short, specific, outcome-oriented
+  - description: problem + scope + constraints
+  - explicit non-goals / out-of-scope
+  - concrete acceptance criteria (testable)
+- Create an execution plan:
+  - add a `## Plan` section to the ticket description
+  - list small, atomic subtasks that are independently committable
+  - ensure the subtask plan covers `loopflowhq/phases/shared-execution-checklist.md`
+- Identify risks/dependencies and document mitigations (migrations, permissions, rollout, data backfills, performance).

package/loopflowhq/phases/story-close.md

@@ -0,0 +1,27 @@
+# Ticket Type: Story - Phase: Close
+
+Goal: finish the loop: ship, document, and leave the system clean.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Approved outcome from Review (or explicit cancellation reason)
+- Any rollout/release constraints
+
+## Outputs (minimum)
+
+- "What shipped" summary
+- Verification steps (and results)
+- Followups created if needed
+
+## Agent checklist
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Confirm Story Review is complete and approved (unless explicitly cancelling):
+  - ticket is `phase=review`, `phase_state=done`
+- Use `loopflowhq/phases/shared-close-checklist.md`.
+- Ensure the ticket summary matches what actually changed.
+- If cancelled, record why and whether a followup is needed.
+- Prefer small cleanup over "nice-to-have" refactors.
+- Run verification (lint/build/test/manual) appropriate to the change before closing.
+