@loopflowhq/agent-pack 0.3.0 → 0.4.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,4 @@
+# lfq-next-best-action — Next best action
+
+Follow `loopflowhq/commands/next-best-action.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
 
@@ -43,15 +39,28 @@ Typed workflow is the canonical model; legacy fields may still be updated for ba
 - Task: `define` -> `implement`
 - 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`
+  - Followup:
+    - review: `loopflowhq/phases/followup-review.md`
+    - close: `loopflowhq/phases/followup-close.md`
 
 ## Transition rules (typed workflow)
 
@@ -59,6 +68,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 +82,29 @@ 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:
+## Required ticket context (before doing work)
 
-- Call `next_best_action` and apply the returned `{ phase, phase_state }` as the next transition.
+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`
+
+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).
-
-Legacy-only clients may instead use `update_ticket_status` with `status` / `substate`, but typed workflow is preferred whenever available.
+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).
 
 ## API-first ticket operations (deterministic)
 
@@ -97,8 +120,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,24 @@
+# Command: Next Best Action
+
+Goal: determine the recommended next workflow transition for a ticket (or pick the next ticket to work on).
+
+## Steps
+
+1. Ensure you have a ticket key/ID. If none is available, ask the user which ticket to use.
+2. Call `next_best_action`.
+   - If a ticket is provided: `next_best_action({ ticket })`
+   - If no ticket is provided: `next_best_action({ limit })`
+3. Report:
+   - selected ticket (id/key/title when present)
+   - current `{ phase, phase_state }`
+   - next `{ phase, phase_state }` (or null)
+
+## Output format
+
+```
+## Next best action
+- Ticket: <KEY or id> — <title>
+- Current: <phase>/<phase_state>
+- Next: <phase>/<phase_state> (or "none")
+```
+

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

@@ -1,9 +1,10 @@
-# Phase: Close
+# Ticket Type: Epic - 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 (or explicit cancellation reason)
 - Any rollout/release constraints
 
@@ -15,7 +16,8 @@ Goal: finish the loop: ship, document, and leave the system clean.
 
 ## Agent checklist
 
+- Load ticket context (see `loopflowhq/agent.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.

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,23 @@
+# Ticket Type: Epic - Phase: Implement
+
+Goal: deliver the epic’s acceptance criteria by implementing planned changes, with tests and minimal risk.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Approved plan
+
+## Outputs (minimum)
+
+- Code changes
+- Tests (or explicit justification if not added)
+- Verification evidence (commands run, expected outputs)
+
+## Agent checklist
+
+- Implement the acceptance criteria from the ticket; if unclear or missing, ask before proceeding.
+- Implement in small diffs; keep changes scoped.
+- Write/update tests that cover the acceptance criteria (or document why tests are not feasible).
+- Run the project’s standard checks (lint/typecheck/test/build) when applicable.
+- Call out any behavior changes and migrations.
+- Do not open a PR unless explicitly requested; shipping is handled separately.

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,13 @@ 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)
+- 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,12 @@ 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)
 
 ## 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,23 @@
+# Ticket Type: Followup - 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 (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`).
+- 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.

package/loopflowhq/phases/followup-review.md

@@ -0,0 +1,23 @@
+# Ticket Type: Followup - Phase: Review
+
+Goal: validate correctness, quality, and alignment with requirements.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Implemented changes
+- Acceptance criteria
+
+## Outputs (minimum)
+
+- Review notes (bugs, risks, missing tests)
+- Decision: approve or request changes
+
+## Agent checklist
+
+- Load ticket context (see `loopflowhq/agent.md`).
+- Prioritize correctness and regressions over style.
+- Ensure acceptance criteria is demonstrably met.
+- If changes are requested, be explicit about what must change and why.
+- If issues are found, fix them and re-review before marking Review done.
+- Post the review notes in the ticket chat (avoid writing `.review/*` files).

package/loopflowhq/phases/story-close.md

@@ -0,0 +1,23 @@
+# 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 (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`).
+- 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.

package/loopflowhq/phases/{implement.md → story-implement.md}

@@ -1,11 +1,11 @@
-# Phase: Implement
+# Ticket Type: Story - Phase: Implement
 
 Goal: make the change in code, with tests and minimal risk.
 
 ## Inputs
 
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
 - Approved plan
-- Acceptance criteria
 
 ## Outputs (minimum)
 
@@ -15,7 +15,9 @@ Goal: make the change in code, with tests and minimal risk.
 
 ## Agent checklist
 
+- Implement the acceptance criteria from the ticket; if unclear or missing, ask before proceeding.
 - Implement in small diffs; keep changes scoped.
+- Write/update tests that cover the acceptance criteria (or document why tests are not feasible).
 - Run the project’s standard checks (lint/typecheck/test/build) when applicable.
 - Call out any behavior changes and migrations.
-
+- Do not open a PR unless explicitly requested; shipping is handled separately.

package/loopflowhq/phases/story-plan.md

@@ -0,0 +1,25 @@
+# Ticket Type: Story - 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)
+
+## Outputs (minimum)
+
+- Step-by-step plan (small diffs)
+- Verification steps (tests/lint/build/manual steps)
+- Risks and rollback plan (if needed)
+- 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/{review.md → story-review.md}

@@ -1,9 +1,10 @@
-# Phase: Review
+# Ticket Type: Story - Phase: Review
 
 Goal: validate correctness, quality, and alignment with requirements.
 
 ## Inputs
 
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
 - Implemented changes
 - Acceptance criteria
 
@@ -14,7 +15,9 @@ Goal: validate correctness, quality, and alignment with requirements.
 
 ## Agent checklist
 
+- Load ticket context (see `loopflowhq/agent.md`).
 - Prioritize correctness and regressions over style.
 - Ensure acceptance criteria is demonstrably met.
 - If changes are requested, be explicit about what must change and why.
-
+- If issues are found, fix them and re-review before marking Review done.
+- Post the review notes in the ticket chat (avoid writing `.review/*` files).

package/loopflowhq/phases/{define.md → task-define.md}

@@ -1,9 +1,10 @@
-# Phase: Define
+# Ticket Type: Task - Phase: Define
 
 Goal: turn a vague task into an executable shape (what, why, constraints).
 
 ## Inputs
 
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
 - Ticket title (may be vague)
 - Any context from prior messages
 
@@ -12,10 +13,12 @@ Goal: turn a vague task into an executable shape (what, why, constraints).
 - Clear problem statement (1-3 sentences)
 - Constraints and non-goals
 - Concrete acceptance criteria (or a proposal to confirm)
+- Define 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.
 - Ask the minimum questions needed to remove ambiguity.
 - Propose acceptance criteria if missing; get confirmation.
 - Identify dependencies/risks early (APIs, migrations, permissions, rollout).
-

package/loopflowhq/phases/task-implement.md

@@ -0,0 +1,23 @@
+# Ticket Type: Task - Phase: Implement
+
+Goal: make the change in code, with tests and minimal risk.
+
+## Inputs
+
+- LoopFlowHQ ticket ID (pattern: `LOOPF-<number>` / regex: `LOOPF-\\d+`)
+- Defined scope + acceptance criteria (from Define phase or ticket)
+
+## Outputs (minimum)
+
+- Code changes
+- Tests (or explicit justification if not added)
+- Verification evidence (commands run, expected outputs)
+
+## Agent checklist
+
+- Implement the acceptance criteria from the ticket; if unclear or missing, ask before proceeding.
+- Implement in small diffs; keep changes scoped.
+- Write/update tests that cover the acceptance criteria (or document why tests are not feasible).
+- Run the project’s standard checks (lint/typecheck/test/build) when applicable.
+- Call out any behavior changes and migrations.
+- Do not open a PR unless explicitly requested; shipping is handled separately.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopflowhq/agent-pack",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "bin": {