@loopflowhq/agent-pack 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cursor/commands/lfq01-discovery.md +24 -0
- package/.cursor/commands/lfq02-planning.md +71 -0
- package/.cursor/commands/lfq03-implementing.md +25 -0
- package/.cursor/commands/lfq04-review.md +85 -0
- package/.cursor/commands/lfq05-testing.md +55 -0
- package/.cursor/commands/lfq06-shipping.md +61 -0
- package/.cursor/commands/lfq07-learning.md +22 -0
- package/.cursor/commands/lfq08-adjusting.md +22 -0
- package/AGENTS.md +14 -0
- package/README.md +22 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +68 -0
- package/dist/cli.js.map +1 -0
- package/dist/install.d.ts +6 -0
- package/dist/install.js +68 -0
- package/dist/install.js.map +1 -0
- package/loopflowhq/README.md +13 -0
- package/loopflowhq/agent.md +111 -0
- package/loopflowhq/phases/close.md +21 -0
- package/loopflowhq/phases/define.md +21 -0
- package/loopflowhq/phases/discovery.md +21 -0
- package/loopflowhq/phases/implement.md +21 -0
- package/loopflowhq/phases/plan.md +21 -0
- package/loopflowhq/phases/refine.md +21 -0
- package/loopflowhq/phases/review.md +20 -0
- package/package.json +30 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# lfq01-discovery — Discovery step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket, and when-done steps (post summary, transition, confirm), follow **lfq-ticket-workflow.md**. This step uses Discovery typed transitions: start with `phase=discovery`, `phase_state=in_progress`, and finish with `phase=discovery`, `phase_state=done` via `update_ticket`.
|
|
8
|
+
|
|
9
|
+
## Discovery work
|
|
10
|
+
|
|
11
|
+
- Explore scope and clarify requirements.
|
|
12
|
+
- Analyze codebase and identify ambiguities.
|
|
13
|
+
- Ask clarification questions **here in this chat**, one at a time (interactive CLI style). Wait for each answer before asking the next. Do **not** send questions via LoopFlowHQ MCP — ask the user directly in the conversation.
|
|
14
|
+
<!-- Optionally post questions/answers to the ticket via `post_ticket_agent_questions` (one at a time) or summarize in `post_ticket_message` when done. -->
|
|
15
|
+
- Document findings for next steps.
|
|
16
|
+
|
|
17
|
+
## Summary example (for post_ticket_message)
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
## Discovery done
|
|
21
|
+
- Scope: [brief]
|
|
22
|
+
- Clarifications received: [key points]
|
|
23
|
+
- Open questions / risks: [if any]
|
|
24
|
+
```
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# lfq02-planning — Planning step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step uses Planning typed transitions: start with `phase=plan`, `phase_state=in_progress`, finish with `phase=plan`, `phase_state=done` via `update_ticket`. Use prior step summaries (e.g. Discovery done) as context.
|
|
8
|
+
|
|
9
|
+
**What this step does:** Read the repo and prior context only. Produce a markdown plan and save it in the LFQ ticket (update ticket description with a **Plan** section via `update_ticket` action / REST API). Do **not** change any files in the repo. Documentation steps (ADRs, feature docs) are only TODOs in the plan—they are done in a later step, not in this phase. **Think:** Does this work require updating the `/privacy` page (e.g. new data collection, third-party services, cookies)? If so, add a plan item for it.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Plan requirements
|
|
14
|
+
|
|
15
|
+
- Include clear, minimal, concise steps.
|
|
16
|
+
- **Scope:** Do NOT add extra scope or unnecessary complexity beyond explicitly clarified details.
|
|
17
|
+
- **Step style:** Steps should be modular, elegant, minimal, and integrate seamlessly within the existing codebase.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Plan structure (save in LFQ ticket)
|
|
22
|
+
|
|
23
|
+
Produce a markdown plan with this structure. Preserve any existing ticket description and add or update a clear `## Plan` section with the content below.
|
|
24
|
+
|
|
25
|
+
**Title**
|
|
26
|
+
After discovery, check the ticket context and adjust the name of the ticket
|
|
27
|
+
|
|
28
|
+
**## TLDR**
|
|
29
|
+
|
|
30
|
+
Short summary of what we're building and why.
|
|
31
|
+
|
|
32
|
+
**## Critical Decisions**
|
|
33
|
+
|
|
34
|
+
Key architectural/implementation choices made during exploration:
|
|
35
|
+
|
|
36
|
+
- Decision 1: [choice] - [brief rationale]
|
|
37
|
+
- Decision 2: [choice] - [brief rationale]
|
|
38
|
+
|
|
39
|
+
**## Documentation**
|
|
40
|
+
|
|
41
|
+
When the work warrants documentation, add **plan items** (TODOs) for later—do not write docs in this phase:
|
|
42
|
+
|
|
43
|
+
- **ADRs** (docs-adr): For significant architectural decisions. Plan path: `docs/decisions/NNN-slug.md`.
|
|
44
|
+
- **Feature docs** (docs-feature): For major features with non-obvious implementation. Plan path: `docs/FEATURE_NAME.md`.
|
|
45
|
+
- **Privacy page** (`/privacy`): When the work involves new data collection, third-party services, cookies, or processing of user data, add a plan item to update the privacy page if required.
|
|
46
|
+
|
|
47
|
+
**## Tasks**
|
|
48
|
+
|
|
49
|
+
- [ ] 🟥 **Step 1: [Name]**
|
|
50
|
+
- [ ] 🟥 Subtask 1
|
|
51
|
+
- [ ] 🟥 Subtask 2
|
|
52
|
+
|
|
53
|
+
- [ ] 🟥 **Step 2: [Name]**
|
|
54
|
+
- [ ] 🟥 Subtask 1
|
|
55
|
+
- [ ] 🟥 Subtask 2
|
|
56
|
+
|
|
57
|
+
- [ ] 🟥 **Document: [Create ADR for X | Create feature doc for Y]** (when warranted)
|
|
58
|
+
|
|
59
|
+
...
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
Again, it's still not time to build yet. Just write the clear plan document. No extra complexity or extra scope beyond what we discussed. Save it in the LFQ ticket by updating the ticket description with a **Plan** section (do not save to a file, do not change any repo files).
|
|
64
|
+
|
|
65
|
+
## Summary example (for post_ticket_message)
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
## Planning done
|
|
69
|
+
- Plan: stored in ticket description (Plan section)
|
|
70
|
+
- Steps: [count]
|
|
71
|
+
```
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# lfq03-implementing — Implementing step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step uses Implementing typed transitions: start with `phase=implement`, `phase_state=in_progress`, finish with `phase=implement`, `phase_state=done` via `update_ticket`. Use prior step summaries (Discovery, Planning) and the plan document (e.g. in `docs/plans/`) as context.
|
|
8
|
+
|
|
9
|
+
## Implementing work
|
|
10
|
+
|
|
11
|
+
- Follow `execute.md`: implement precisely as planned.
|
|
12
|
+
- Update the plan document with emoji status as you progress.
|
|
13
|
+
- Adhere to project rules (Design, coding-patterns, UX).
|
|
14
|
+
- **Do not** create a branch, commit, or open a PR in this step.
|
|
15
|
+
|
|
16
|
+
## When implementation is done
|
|
17
|
+
|
|
18
|
+
- Post the summary via `post_ticket_message`, then call `update_ticket` with `phase=implement` and `phase_state=done`. Do not run git commit or advance the ticket to the next step.
|
|
19
|
+
|
|
20
|
+
## Summary example (for post_ticket_message)
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
## Implementing done
|
|
24
|
+
- Changes: [brief list of files/areas touched]
|
|
25
|
+
```
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# lfq04-review — Review step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step uses Review typed transitions: start with `phase=review`, `phase_state=in_progress`, finish with `phase=review`, `phase_state=done` via `update_ticket`. Use prior step summaries (Implementing done) as context.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Perform code review
|
|
12
|
+
|
|
13
|
+
Follow the same checks and output structure as **review.md**:
|
|
14
|
+
|
|
15
|
+
**Check for:**
|
|
16
|
+
|
|
17
|
+
- **Logging** — No console.log, use proper logger with context
|
|
18
|
+
- **Error handling** — Try-catch for async, centralized handlers, helpful messages
|
|
19
|
+
- **TypeScript** — No `any`, proper interfaces, no @ts-ignore
|
|
20
|
+
- **Production readiness** — No debug statements, no TODOs, no hardcoded secrets
|
|
21
|
+
- **React/Hooks** — Effects have cleanup, dependencies complete, no infinite loops
|
|
22
|
+
- **Performance** — No unnecessary re-renders, expensive calcs memoized
|
|
23
|
+
- **Security** — Auth checked, inputs validated, RLS in place
|
|
24
|
+
- **Architecture** — Follows existing patterns, code in correct directory
|
|
25
|
+
|
|
26
|
+
**Severity levels:** CRITICAL (security, data loss, crashes), HIGH (bugs, performance, bad UX), MEDIUM (code quality, maintainability), LOW (style, minor).
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 2. Fix all issues, then re-review
|
|
31
|
+
|
|
32
|
+
- If **any issues** are found (Critical, High, Medium, or Low):
|
|
33
|
+
1. **Fix every issue** (apply suggested fixes or equivalent).
|
|
34
|
+
2. **Re-run the review** on the changed code until there are no remaining issues, or you explicitly document why a finding is not fixed (e.g. deferred, out of scope).
|
|
35
|
+
- Only after all issues are fixed or documented do you post the review and mark the step done.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 3. Store review in ticket chat (no .review files)
|
|
40
|
+
|
|
41
|
+
- **Do not** write the review to `.review/<ticket-key>.md` or any file under `.review/`.
|
|
42
|
+
- Post the **full review** as a single ticket message using **`post_ticket_message`** so the review lives in the ticket chat.
|
|
43
|
+
|
|
44
|
+
**Message content format** (use this exact structure in the posted message):
|
|
45
|
+
|
|
46
|
+
```markdown
|
|
47
|
+
## Code review
|
|
48
|
+
|
|
49
|
+
### ✅ Looks Good
|
|
50
|
+
|
|
51
|
+
- [Item 1]
|
|
52
|
+
- [Item 2]
|
|
53
|
+
|
|
54
|
+
### ⚠️ Issues Found
|
|
55
|
+
|
|
56
|
+
- **[Severity]** [File:line] - [Issue description]
|
|
57
|
+
- Fix: [Suggested fix]
|
|
58
|
+
(If none: "None.")
|
|
59
|
+
|
|
60
|
+
### 📊 Summary
|
|
61
|
+
|
|
62
|
+
- Files reviewed: X
|
|
63
|
+
- Critical issues: 0 (after fixes)
|
|
64
|
+
- Warnings: 0 (after fixes)
|
|
65
|
+
|
|
66
|
+
**Outcome:** Passed. [One line: e.g. "Changes are minimal and follow existing patterns." / "All issues fixed and re-verified."]
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Then add the step-done line:
|
|
70
|
+
|
|
71
|
+
```markdown
|
|
72
|
+
## Review done
|
|
73
|
+
|
|
74
|
+
- Outcome: [passed / issues fixed and re-verified]
|
|
75
|
+
- Critical issues: 0
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
(You may combine the "Code review" and "Review done" blocks into one `post_ticket_message` call.)
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 4. Mark step done
|
|
83
|
+
|
|
84
|
+
- Call **`update_ticket`** with `ticket`, `phase`: `review`, `phase_state`: `done` (legacy `status` should stay compatible).
|
|
85
|
+
- Confirm to the user that the review step is complete and the ticket is ready for the next step (e.g. testing).
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# lfq05-testing — Testing step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step validates release readiness and keeps ticket in close-stage execution (`phase=close`, typically `phase_state=in_progress`). Use prior step summaries (Implementing, Review) as context.
|
|
8
|
+
|
|
9
|
+
**Do not:** Create a PR or push commits in this step. Commit, push, and PR creation belong to the Shipping step (lfq06-shipping).
|
|
10
|
+
|
|
11
|
+
## Understand ticket and acceptance criteria
|
|
12
|
+
|
|
13
|
+
1. **Ticket description** — Read and understand the full ticket description. Ensure you know what the ticket is asking for.
|
|
14
|
+
2. **Acceptance criteria** — If the ticket has acceptance criteria (e.g. in the description or as a list), treat them as the source of truth for "done."
|
|
15
|
+
3. **Validate implementation** — Go through each acceptance criterion and confirm it is implemented in code or behavior. If any are missing, implement or fix before considering testing complete.
|
|
16
|
+
4. **Validate docs** — If the change affects architecture, behavior, or features, ensure the appropriate docs are updated (e.g. ADRs in `docs/adr/`, feature docs in `docs/`, READMEs). Documentation should match the current implementation.
|
|
17
|
+
|
|
18
|
+
## Testing work
|
|
19
|
+
|
|
20
|
+
1. **Clean debug code** — Before running the linter, remove all debug code:
|
|
21
|
+
- Remove all `console.log` statements (except browser `console.log` relevant to users in production)
|
|
22
|
+
- Remove any debug logs calling `127.0.0.1` or `localhost`
|
|
23
|
+
- Clean up any temporary debug code
|
|
24
|
+
|
|
25
|
+
2. **Run linter** — Execute `npm run lint` to check code quality and catch any linting issues in **all projects** in `apps/` (e.g. webapp and website).
|
|
26
|
+
|
|
27
|
+
3. **Test build** — Run `npm run build` to ensure **all projects** build successfully without errors.
|
|
28
|
+
|
|
29
|
+
4. **Run tests** — Execute `npm run test` to run all test suites in **all projects** and ensure everything passes.
|
|
30
|
+
|
|
31
|
+
5. **Manual verification** — If applicable, run the dev server and smoke-test the change (e.g. key flows, UI, or APIs).
|
|
32
|
+
|
|
33
|
+
6. **Address issues** — Fix any failures or issues found during lint, build, tests, or manual verification.
|
|
34
|
+
|
|
35
|
+
## Checklist
|
|
36
|
+
|
|
37
|
+
- [ ] Ticket description understood; acceptance criteria (if any) identified
|
|
38
|
+
- [ ] All acceptance criteria validated as implemented
|
|
39
|
+
- [ ] Appropriate docs updated (ADRs, feature docs in `docs/`, etc.) and match implementation
|
|
40
|
+
- [ ] Debug code cleaned up (console.log, 127.0.0.1 calls, etc.)
|
|
41
|
+
- [ ] Linter passes with no errors for **all projects** in `apps/`
|
|
42
|
+
- [ ] Build completes successfully for **all projects** in `apps/`
|
|
43
|
+
- [ ] All tests pass for **all projects** in `apps/`
|
|
44
|
+
- [ ] Manual verification done if applicable
|
|
45
|
+
|
|
46
|
+
## Summary example (for post_ticket_message)
|
|
47
|
+
|
|
48
|
+
```
|
|
49
|
+
## Testing done
|
|
50
|
+
- Ticket/AC: [brief note that description and acceptance criteria were checked and met]
|
|
51
|
+
- Docs: [updated / N/A]
|
|
52
|
+
- Tests: passing
|
|
53
|
+
- Build: passing
|
|
54
|
+
- Notes: [any manual verification]
|
|
55
|
+
```
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# lfq06-shipping — Shipping step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step executes close/shipping work: keep `phase=close`, move from `phase_state=in_progress` to `phase_state=done` when shipping is complete. Use prior step summaries (PR link, branch) as context.
|
|
8
|
+
|
|
9
|
+
## 1. Ensure we are not on main with uncommitted changes
|
|
10
|
+
|
|
11
|
+
If `git branch --show-current` is `main` **and** `git status --porcelain` is non-empty:
|
|
12
|
+
|
|
13
|
+
1. **Derive branch name from uncommitted files** (see create-branch.md as inspiration):
|
|
14
|
+
- Run `git status --porcelain` to inspect changed files
|
|
15
|
+
- Infer type from paths: `docs/` → docs, `*.test.*` or `__tests__/` → test, config files → chore, `.github/` → ci, CSS → style, bug-fix cues → fix, new components/features → feat, refactors → refactor, perf cues → perf
|
|
16
|
+
- Suggest branch name: `<type>/short-description` (e.g. `feat/LOOPF-30-substate-icons`). Ask user if unclear
|
|
17
|
+
2. **Move uncommitted changes onto a new branch** (same flow as create-branch.md):
|
|
18
|
+
- `git stash push -u -m "cursor-ship"`
|
|
19
|
+
- `git fetch origin main` && `git pull origin main`
|
|
20
|
+
- `git checkout -b <branch-name>`
|
|
21
|
+
- `git stash pop`
|
|
22
|
+
|
|
23
|
+
If already on a feature branch with uncommitted changes, skip to step 2. If on main with no changes and no existing PR, ask the user what to ship.
|
|
24
|
+
|
|
25
|
+
## 2. Commit and push
|
|
26
|
+
|
|
27
|
+
- Stage changes: `git add .` (or stage selectively)
|
|
28
|
+
- **Commit message:** Follow Conventional Commits (commitlint / husky). Format: `type(scope): subject` with optional body bullets. Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `revert`. Scope: `web`, `api`, `mcp`, `deps`, `ci`, `docs`. Subject: imperative, lowercase.
|
|
29
|
+
- Commit: `git commit -m "..."` (use `-F` with temp file if multi-line)
|
|
30
|
+
- Push: `git push -u origin <branch>`
|
|
31
|
+
|
|
32
|
+
## 3. Prepare a PR
|
|
33
|
+
|
|
34
|
+
- Create PR targeting `main`
|
|
35
|
+
- **PR title:** Use same Conventional Commits format as the commit (e.g. `feat(web): add substate icons`) — release-please parses PR titles and merge commits for changelog
|
|
36
|
+
- **PR body:** Reference ticket(s), e.g. `Closes LOOPF-30` or `Related to LOOPF-30`
|
|
37
|
+
- Do **not** merge the PR unless the user explicitly asks to merge
|
|
38
|
+
|
|
39
|
+
### PR title gating (required)
|
|
40
|
+
|
|
41
|
+
- **Husky only checks local commit messages**, not PR titles.
|
|
42
|
+
- Add a PR title check in CI so merges are blocked unless the title is Conventional Commits:
|
|
43
|
+
- Recommended: use `amannn/action-semantic-pull-request` in `.github/workflows/pr-title.yml` and require it in branch protection.
|
|
44
|
+
- If a PR title fails, fix the title before merge so the merge commit is parseable by release-please.
|
|
45
|
+
|
|
46
|
+
## 4. Post-PR shipping work (when PR exists)
|
|
47
|
+
|
|
48
|
+
- Merge the PR to `main` **only if the user explicitly requests it**
|
|
49
|
+
|
|
50
|
+
## 5. Mark tickets done
|
|
51
|
+
|
|
52
|
+
When shipping work is complete (PR created and, if requested, merged): call `update_ticket` with `phase=close`, `phase_state=done` (and compatible legacy `status`). Post summary via `post_ticket_message`.
|
|
53
|
+
|
|
54
|
+
## Summary example (for post_ticket_message)
|
|
55
|
+
|
|
56
|
+
```
|
|
57
|
+
## Shipping done
|
|
58
|
+
- Branch: [branch name]
|
|
59
|
+
- PR: [PR link]
|
|
60
|
+
- Merged: [yes/no, PR link if merged]
|
|
61
|
+
```
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# lfq07-learning — Learning step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step is a post-delivery analysis step; it usually does not require a phase change and should keep typed workflow coherent for the ticket type. Use prior step summaries (what was shipped, outcomes) as context.
|
|
8
|
+
|
|
9
|
+
## Learning work
|
|
10
|
+
|
|
11
|
+
- Reflect on what was delivered: outcomes, metrics, user feedback if available.
|
|
12
|
+
- Document lessons learned, surprises, or improvements for next time.
|
|
13
|
+
- Identify any adjustments to process or scope.
|
|
14
|
+
|
|
15
|
+
## Summary example (for post_ticket_message)
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
## Learning done
|
|
19
|
+
- Outcomes: [what we observed]
|
|
20
|
+
- Lessons: [key takeaways]
|
|
21
|
+
- Adjustments: [if any]
|
|
22
|
+
```
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# lfq08-adjusting — Adjusting step
|
|
2
|
+
|
|
3
|
+
**Requirement:** Ticket key or URL may be in the command; if omitted, infer from conversation context (see lfq-ticket-workflow.md §1). Ask only if no ticket can be inferred or if multiple tickets are referenced and the intended one is unclear.
|
|
4
|
+
|
|
5
|
+
**When asking questions:** Use an interactive CLI style — ask one question at a time, wait for the user's answer, then ask the next. This makes it easier to answer.
|
|
6
|
+
|
|
7
|
+
**Ticket workflow:** For resolve ticket ID, load ticket and context, and when-done steps, follow **lfq-ticket-workflow.md**. This step applies post-delivery adjustments (often via followup tickets) and should keep typed workflow coherent with the ticket type. Use prior step summaries (Learning done, lessons) as context.
|
|
8
|
+
|
|
9
|
+
## Adjusting work
|
|
10
|
+
|
|
11
|
+
- Based on Learning outcomes: apply process or scope adjustments.
|
|
12
|
+
- Create follow-up tickets if needed.
|
|
13
|
+
- Update documentation or runbooks.
|
|
14
|
+
- Decide if ticket can move to Done.
|
|
15
|
+
|
|
16
|
+
## Summary example (for post_ticket_message)
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
## Adjusting done
|
|
20
|
+
- Adjustments: [what was done]
|
|
21
|
+
- Follow-ups: [ticket keys if any]
|
|
22
|
+
```
|
package/AGENTS.md
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
LoopFlowHQ-managed file.
|
|
3
|
+
|
|
4
|
+
Do not edit directly.
|
|
5
|
+
To update: npx @loopflowhq/agent-pack@latest install
|
|
6
|
+
-->
|
|
7
|
+
|
|
8
|
+
# LoopFlowHQ Agent Rules
|
|
9
|
+
|
|
10
|
+
LoopFlowHQ is a workflow for humans and coding agents to collaborate via tickets.
|
|
11
|
+
|
|
12
|
+
Before doing any work, you must read and follow:
|
|
13
|
+
|
|
14
|
+
- `loopflowhq/agent.md` (canonical workflow + authority model)
|
package/README.md
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# @loopflowhq/agent-pack
|
|
2
|
+
|
|
3
|
+
One-command installer/updater for LoopFlowHQ-managed agent files.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# install (or update) into the current repo
|
|
9
|
+
npx @loopflowhq/agent-pack@latest install
|
|
10
|
+
|
|
11
|
+
# install (or update) into another folder
|
|
12
|
+
npx @loopflowhq/agent-pack@latest install --cwd ../some-repo
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## What it writes
|
|
16
|
+
|
|
17
|
+
- `.cursor/commands/lfq*.md`
|
|
18
|
+
- `AGENTS.md`
|
|
19
|
+
- `loopflowhq/**`
|
|
20
|
+
- `.loopflowhq/version.json`
|
|
21
|
+
|
|
22
|
+
All installed files are marked as LoopFlowHQ-managed and can be updated by rerunning the installer.
|
package/dist/cli.d.ts
ADDED
package/dist/cli.js
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import fs from 'node:fs/promises';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
import { installAgentPack } from './install.js';
|
|
5
|
+
async function getPackageVersion() {
|
|
6
|
+
try {
|
|
7
|
+
const pkgUrl = new URL('../package.json', import.meta.url);
|
|
8
|
+
const raw = await fs.readFile(pkgUrl, 'utf8');
|
|
9
|
+
const pkg = JSON.parse(raw);
|
|
10
|
+
return typeof pkg.version === 'string' && pkg.version ? pkg.version : '0.0.0';
|
|
11
|
+
}
|
|
12
|
+
catch {
|
|
13
|
+
return '0.0.0';
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
function usage() {
|
|
17
|
+
return `loopflowhq-agent-pack
|
|
18
|
+
|
|
19
|
+
Usage:
|
|
20
|
+
npx @loopflowhq/agent-pack@latest install [--cwd <path>]
|
|
21
|
+
|
|
22
|
+
Behavior:
|
|
23
|
+
Writes LoopFlowHQ-managed files into the target repo:
|
|
24
|
+
- .cursor/commands/lfq*.md
|
|
25
|
+
- AGENTS.md
|
|
26
|
+
- .loopflowhq/version.json
|
|
27
|
+
`;
|
|
28
|
+
}
|
|
29
|
+
function parseArgs(argv) {
|
|
30
|
+
const args = argv.slice(2);
|
|
31
|
+
const cmd = args[0] ?? 'install';
|
|
32
|
+
let cwd = process.cwd();
|
|
33
|
+
for (let i = 1; i < args.length; i += 1) {
|
|
34
|
+
const token = args[i];
|
|
35
|
+
if (token === '--cwd') {
|
|
36
|
+
const next = args[i + 1];
|
|
37
|
+
if (!next)
|
|
38
|
+
throw new Error('Missing value for --cwd');
|
|
39
|
+
cwd = path.resolve(process.cwd(), next);
|
|
40
|
+
i += 1;
|
|
41
|
+
}
|
|
42
|
+
if (token === '-h' || token === '--help') {
|
|
43
|
+
return { cmd: 'help', cwd };
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
return { cmd, cwd };
|
|
47
|
+
}
|
|
48
|
+
async function main() {
|
|
49
|
+
const { cmd, cwd } = parseArgs(process.argv);
|
|
50
|
+
if (cmd === 'help') {
|
|
51
|
+
process.stdout.write(usage());
|
|
52
|
+
return;
|
|
53
|
+
}
|
|
54
|
+
if (cmd !== 'install') {
|
|
55
|
+
process.stderr.write(`Unknown command: ${cmd}\n\n`);
|
|
56
|
+
process.stderr.write(usage());
|
|
57
|
+
process.exitCode = 1;
|
|
58
|
+
return;
|
|
59
|
+
}
|
|
60
|
+
const version = await getPackageVersion();
|
|
61
|
+
await installAgentPack({ cwd, version });
|
|
62
|
+
process.stdout.write(`Installed LoopFlowHQ agent pack into: ${cwd}\n`);
|
|
63
|
+
}
|
|
64
|
+
main().catch((err) => {
|
|
65
|
+
process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
|
|
66
|
+
process.exitCode = 1;
|
|
67
|
+
});
|
|
68
|
+
//# sourceMappingURL=cli.js.map
|
package/dist/cli.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
|
package/dist/install.js
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import fs from 'node:fs/promises';
|
|
2
|
+
import path from 'node:path';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
4
|
+
const MANAGED_HEADER = `<!--\nLoopFlowHQ-managed file.\n\nDo not edit directly.\nTo update: npx @loopflowhq/agent-pack@latest install\n-->\n\n`;
|
|
5
|
+
function shouldPrependManagedHeader(content) {
|
|
6
|
+
return !content.includes('LoopFlowHQ-managed file');
|
|
7
|
+
}
|
|
8
|
+
async function ensureDir(p) {
|
|
9
|
+
await fs.mkdir(p, { recursive: true });
|
|
10
|
+
}
|
|
11
|
+
async function writeFileEnsuringParent(filePath, content) {
|
|
12
|
+
await ensureDir(path.dirname(filePath));
|
|
13
|
+
await fs.writeFile(filePath, content, 'utf8');
|
|
14
|
+
}
|
|
15
|
+
async function copyMarkdownWithHeader(params) {
|
|
16
|
+
const raw = await fs.readFile(params.from, 'utf8');
|
|
17
|
+
const out = shouldPrependManagedHeader(raw)
|
|
18
|
+
? params.header + raw
|
|
19
|
+
: raw;
|
|
20
|
+
await writeFileEnsuringParent(params.to, out);
|
|
21
|
+
}
|
|
22
|
+
async function copyMarkdownTreeWithHeader(params) {
|
|
23
|
+
const entries = await fs.readdir(params.fromDir, { withFileTypes: true });
|
|
24
|
+
for (const entry of entries) {
|
|
25
|
+
const from = path.join(params.fromDir, entry.name);
|
|
26
|
+
const to = path.join(params.toDir, entry.name);
|
|
27
|
+
if (entry.isDirectory()) {
|
|
28
|
+
await copyMarkdownTreeWithHeader({ fromDir: from, toDir: to, header: params.header });
|
|
29
|
+
continue;
|
|
30
|
+
}
|
|
31
|
+
if (!entry.isFile())
|
|
32
|
+
continue;
|
|
33
|
+
if (!entry.name.endsWith('.md'))
|
|
34
|
+
continue;
|
|
35
|
+
await copyMarkdownWithHeader({ from, to, header: params.header });
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
export async function installAgentPack(opts) {
|
|
39
|
+
const now = opts.now ?? new Date();
|
|
40
|
+
// Packaged sources are synced from the repo root into the npm package root at build time.
|
|
41
|
+
// See: scripts/sync-templates.mjs
|
|
42
|
+
const packageRoot = fileURLToPath(new URL('../', import.meta.url));
|
|
43
|
+
const cursorCommandsSrc = path.join(packageRoot, '.cursor/commands');
|
|
44
|
+
const cursorCommandsDst = path.join(opts.cwd, '.cursor/commands');
|
|
45
|
+
await ensureDir(cursorCommandsDst);
|
|
46
|
+
const entries = await fs.readdir(cursorCommandsSrc, { withFileTypes: true });
|
|
47
|
+
for (const entry of entries) {
|
|
48
|
+
if (!entry.isFile())
|
|
49
|
+
continue;
|
|
50
|
+
if (!entry.name.endsWith('.md'))
|
|
51
|
+
continue;
|
|
52
|
+
const from = path.join(cursorCommandsSrc, entry.name);
|
|
53
|
+
const to = path.join(cursorCommandsDst, entry.name);
|
|
54
|
+
await copyMarkdownWithHeader({ from, to, header: MANAGED_HEADER });
|
|
55
|
+
}
|
|
56
|
+
const agentsSrc = path.join(packageRoot, 'AGENTS.md');
|
|
57
|
+
const agentsDst = path.join(opts.cwd, 'AGENTS.md');
|
|
58
|
+
await copyMarkdownWithHeader({ from: agentsSrc, to: agentsDst, header: MANAGED_HEADER });
|
|
59
|
+
const loopflowhqSrc = path.join(packageRoot, 'loopflowhq');
|
|
60
|
+
const loopflowhqDst = path.join(opts.cwd, 'loopflowhq');
|
|
61
|
+
await copyMarkdownTreeWithHeader({ fromDir: loopflowhqSrc, toDir: loopflowhqDst, header: MANAGED_HEADER });
|
|
62
|
+
const markerPath = path.join(opts.cwd, '.loopflowhq/version.json');
|
|
63
|
+
await writeFileEnsuringParent(markerPath, JSON.stringify({
|
|
64
|
+
agent_pack_version: opts.version,
|
|
65
|
+
installed_at: now.toISOString(),
|
|
66
|
+
}, null, 2) + '\n');
|
|
67
|
+
}
|
|
68
|
+
//# sourceMappingURL=install.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# LoopFlowHQ Workflow Docs
|
|
2
|
+
|
|
3
|
+
The canonical, prompt-ready workflow description for agents lives in `loopflowhq/agent.md`.
|
|
4
|
+
|
|
5
|
+
Phase playbooks:
|
|
6
|
+
|
|
7
|
+
- `loopflowhq/phases/define.md`
|
|
8
|
+
- `loopflowhq/phases/discovery.md`
|
|
9
|
+
- `loopflowhq/phases/refine.md`
|
|
10
|
+
- `loopflowhq/phases/plan.md`
|
|
11
|
+
- `loopflowhq/phases/implement.md`
|
|
12
|
+
- `loopflowhq/phases/review.md`
|
|
13
|
+
- `loopflowhq/phases/close.md`
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# LoopFlowHQ Workflow (Prompt-Ready)
|
|
2
|
+
|
|
3
|
+
This file is the canonical, repo-local description of how LoopFlowHQ work. It is written to be copied into a production prompt or referenced by coding agents.
|
|
4
|
+
|
|
5
|
+
## Mental model
|
|
6
|
+
|
|
7
|
+
- LoopFlowHQ is a human+agent workflow.
|
|
8
|
+
- Agents execute work quickly; humans own acceptance gates.
|
|
9
|
+
- Workflow state is explicit on the ticket and should be kept correct while work progresses.
|
|
10
|
+
|
|
11
|
+
## Authority (non-negotiable)
|
|
12
|
+
|
|
13
|
+
- Humans own:
|
|
14
|
+
- Epic completion gates
|
|
15
|
+
- Story review approval (final accept/reject)
|
|
16
|
+
- Agents may:
|
|
17
|
+
- Execute implementation work
|
|
18
|
+
- Move agent-owned workflow transitions when allowed by the workflow.
|
|
19
|
+
- Never do silent scope creep. If requirements are unclear, ask.
|
|
20
|
+
|
|
21
|
+
## Vocabulary
|
|
22
|
+
|
|
23
|
+
- `phase`: typed workflow phase (what kind of work is happening)
|
|
24
|
+
- `phase_state`: progress within a phase
|
|
25
|
+
- Legacy fields exist for compatibility:
|
|
26
|
+
- `status` / `substate` (older workflow model)
|
|
27
|
+
|
|
28
|
+
Typed workflow is the canonical model; legacy fields may still be updated for backward compatibility.
|
|
29
|
+
|
|
30
|
+
## Canonical typed workflow
|
|
31
|
+
|
|
32
|
+
### `phase_state` values
|
|
33
|
+
|
|
34
|
+
- `ready`: queued for work in this phase
|
|
35
|
+
- `in_progress`: actively being worked on
|
|
36
|
+
- `done`: phase complete
|
|
37
|
+
- `changes_requested`: rejected at this phase; must rework then retry
|
|
38
|
+
|
|
39
|
+
### Phases by ticket type
|
|
40
|
+
|
|
41
|
+
- Epic: `discovery` -> `refine` -> `plan` -> `implement` -> `close`
|
|
42
|
+
- Story: `plan` -> `implement` -> `review` -> `close`
|
|
43
|
+
- Task: `define` -> `implement`
|
|
44
|
+
- Followup: `review` -> `close`
|
|
45
|
+
|
|
46
|
+
See phase playbooks:
|
|
47
|
+
|
|
48
|
+
- `loopflowhq/phases/define.md`
|
|
49
|
+
- `loopflowhq/phases/discovery.md`
|
|
50
|
+
- `loopflowhq/phases/refine.md`
|
|
51
|
+
- `loopflowhq/phases/plan.md`
|
|
52
|
+
- `loopflowhq/phases/implement.md`
|
|
53
|
+
- `loopflowhq/phases/review.md`
|
|
54
|
+
- `loopflowhq/phases/close.md`
|
|
55
|
+
|
|
56
|
+
## Transition rules (typed workflow)
|
|
57
|
+
|
|
58
|
+
Within a phase, the normal progression is:
|
|
59
|
+
|
|
60
|
+
- `ready` -> `in_progress` -> `done`
|
|
61
|
+
|
|
62
|
+
When feedback fails a gate in the current phase:
|
|
63
|
+
|
|
64
|
+
- `in_progress` -> `changes_requested` (or directly set `changes_requested`)
|
|
65
|
+
- Then: `changes_requested` -> `ready` (to rework)
|
|
66
|
+
|
|
67
|
+
Moving to the next phase:
|
|
68
|
+
|
|
69
|
+
- When a phase is `done`, the next phase starts at `ready`.
|
|
70
|
+
|
|
71
|
+
If you are an agent with tool access, prefer to ask LoopFlowHQ for the next move instead of guessing:
|
|
72
|
+
|
|
73
|
+
- Call `next_best_action` and apply the returned `{ phase, phase_state }` as the next transition.
|
|
74
|
+
|
|
75
|
+
## How to talk to LoopFlowHQ (tools)
|
|
76
|
+
|
|
77
|
+
If MCP / Actions tools are available, the standard loop is:
|
|
78
|
+
|
|
79
|
+
1. `get_ticket` (+ `get_ticket_messages`) to load context.
|
|
80
|
+
2. `next_best_action` to confirm the recommended transition.
|
|
81
|
+
3. `update_ticket` (preferred) to set `phase` / `phase_state` as you start and finish a step.
|
|
82
|
+
4. `post_ticket_message` to write a concise step summary (what changed, what was decided, what is next).
|
|
83
|
+
|
|
84
|
+
Legacy-only clients may instead use `update_ticket_status` with `status` / `substate`, but typed workflow is preferred whenever available.
|
|
85
|
+
|
|
86
|
+
## API-first ticket operations (deterministic)
|
|
87
|
+
|
|
88
|
+
When you need deterministic ticket CRUD, prefer the LoopFlowHQ Actions REST API when it is available in your environment.
|
|
89
|
+
|
|
90
|
+
- Base URL: `https://www.loopflowhq.com/api/chatgpt-actions`
|
|
91
|
+
- Auth: `Authorization: Bearer lfhq_...` (or `?api_key=lfhq_...`)
|
|
92
|
+
- Method: `POST`
|
|
93
|
+
|
|
94
|
+
Common actions:
|
|
95
|
+
|
|
96
|
+
- List: `POST /list_my_tickets`
|
|
97
|
+
- Read: `POST /get_ticket`
|
|
98
|
+
- Messages: `POST /get_ticket_messages`
|
|
99
|
+
- Create: `POST /create_ticket`
|
|
100
|
+
- Update fields (preferred): `POST /update_ticket`
|
|
101
|
+
- Legacy status/substate (fallback): `POST /update_ticket_status`
|
|
102
|
+
- Post message: `POST /post_ticket_message`
|
|
103
|
+
- Post agent questions: `POST /post_ticket_agent_questions`
|
|
104
|
+
|
|
105
|
+
Use MCP when the task is reasoning-centric (brainstorming, planning, ambiguity resolution) or when REST is not available.
|
|
106
|
+
|
|
107
|
+
## What "done" means
|
|
108
|
+
|
|
109
|
+
- Workflow "done" is not the same as "accepted".
|
|
110
|
+
- A ticket may be `phase=review` / `phase_state=done` and still need human approval to be truly accepted.
|
|
111
|
+
- Do not mark human-owned gates complete unless explicitly instructed by the human owner.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Phase: Close
|
|
2
|
+
|
|
3
|
+
Goal: finish the loop: ship, document, and leave the system clean.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Approved outcome (or explicit cancellation reason)
|
|
8
|
+
- Any rollout/release constraints
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- “What shipped” summary
|
|
13
|
+
- Verification steps (and results)
|
|
14
|
+
- Followups created if needed
|
|
15
|
+
|
|
16
|
+
## Agent checklist
|
|
17
|
+
|
|
18
|
+
- Ensure the ticket summary matches what actually changed.
|
|
19
|
+
- If cancelled, record why and whether a followup is needed.
|
|
20
|
+
- Prefer small cleanup over “nice-to-have” refactors.
|
|
21
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Phase: Define
|
|
2
|
+
|
|
3
|
+
Goal: turn a vague task into an executable shape (what, why, constraints).
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Ticket title (may be vague)
|
|
8
|
+
- Any context from prior messages
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- Clear problem statement (1-3 sentences)
|
|
13
|
+
- Constraints and non-goals
|
|
14
|
+
- Concrete acceptance criteria (or a proposal to confirm)
|
|
15
|
+
|
|
16
|
+
## Agent checklist
|
|
17
|
+
|
|
18
|
+
- Ask the minimum questions needed to remove ambiguity.
|
|
19
|
+
- Propose acceptance criteria if missing; get confirmation.
|
|
20
|
+
- Identify dependencies/risks early (APIs, migrations, permissions, rollout).
|
|
21
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Phase: Discovery
|
|
2
|
+
|
|
3
|
+
Goal: explore scope and reduce uncertainty before committing to a solution.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Problem statement and constraints
|
|
8
|
+
- Existing system context (code, docs, prior tickets)
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- Clarified requirements and edge cases
|
|
13
|
+
- Proposed approach options (if needed) with tradeoffs
|
|
14
|
+
- A narrowed, agreed scope
|
|
15
|
+
|
|
16
|
+
## Agent checklist
|
|
17
|
+
|
|
18
|
+
- Identify what is unknown and what must be decided by a human.
|
|
19
|
+
- Validate assumptions against the codebase when possible.
|
|
20
|
+
- If requirements are missing, ask targeted questions instead of guessing.
|
|
21
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Phase: Implement
|
|
2
|
+
|
|
3
|
+
Goal: make the change in code, with tests and minimal risk.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Approved plan
|
|
8
|
+
- Acceptance criteria
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- Code changes
|
|
13
|
+
- Tests (or explicit justification if not added)
|
|
14
|
+
- Verification evidence (commands run, expected outputs)
|
|
15
|
+
|
|
16
|
+
## Agent checklist
|
|
17
|
+
|
|
18
|
+
- Implement in small diffs; keep changes scoped.
|
|
19
|
+
- Run the project’s standard checks (lint/typecheck/test/build) when applicable.
|
|
20
|
+
- Call out any behavior changes and migrations.
|
|
21
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Phase: Plan
|
|
2
|
+
|
|
3
|
+
Goal: decide the smallest safe implementation plan with verification.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Final requirements + acceptance criteria
|
|
8
|
+
- System constraints (tech stack, performance, security, rollout)
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- Step-by-step plan (small diffs)
|
|
13
|
+
- Verification steps (tests/lint/build/manual steps)
|
|
14
|
+
- Risks and rollback plan (if needed)
|
|
15
|
+
|
|
16
|
+
## Agent checklist
|
|
17
|
+
|
|
18
|
+
- Keep the plan minimal and aligned with current project patterns.
|
|
19
|
+
- Identify where human approval is needed (review gates, product decisions).
|
|
20
|
+
- Prefer “prove it” steps (tests, screenshots, logs) over promises.
|
|
21
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Phase: Refine
|
|
2
|
+
|
|
3
|
+
Goal: turn discovery output into a precise, buildable specification.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Discovery notes and decisions
|
|
8
|
+
- Existing constraints (time, architecture, UX expectations)
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- Finalized acceptance criteria
|
|
13
|
+
- Non-goals and explicit exclusions
|
|
14
|
+
- Implementation shape (high-level architecture, key files/modules)
|
|
15
|
+
|
|
16
|
+
## Agent checklist
|
|
17
|
+
|
|
18
|
+
- Ensure acceptance criteria is testable and unambiguous.
|
|
19
|
+
- Surface any scope creep since Discovery and ask for confirmation.
|
|
20
|
+
- Call out any “this changes behavior” items explicitly.
|
|
21
|
+
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Phase: Review
|
|
2
|
+
|
|
3
|
+
Goal: validate correctness, quality, and alignment with requirements.
|
|
4
|
+
|
|
5
|
+
## Inputs
|
|
6
|
+
|
|
7
|
+
- Implemented changes
|
|
8
|
+
- Acceptance criteria
|
|
9
|
+
|
|
10
|
+
## Outputs (minimum)
|
|
11
|
+
|
|
12
|
+
- Review notes (bugs, risks, missing tests)
|
|
13
|
+
- Decision: approve or request changes
|
|
14
|
+
|
|
15
|
+
## Agent checklist
|
|
16
|
+
|
|
17
|
+
- Prioritize correctness and regressions over style.
|
|
18
|
+
- Ensure acceptance criteria is demonstrably met.
|
|
19
|
+
- If changes are requested, be explicit about what must change and why.
|
|
20
|
+
|
package/package.json
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@loopflowhq/agent-pack",
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"private": false,
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"loopflowhq-agent-pack": "dist/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"publishConfig": {
|
|
10
|
+
"access": "public"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist/**",
|
|
14
|
+
".cursor/commands/**",
|
|
15
|
+
"loopflowhq/**",
|
|
16
|
+
"AGENTS.md",
|
|
17
|
+
"README.md"
|
|
18
|
+
],
|
|
19
|
+
"scripts": {
|
|
20
|
+
"build": "node scripts/sync-templates.mjs && tsc -p tsconfig.json",
|
|
21
|
+
"test": "npm run build && node --test",
|
|
22
|
+
"lint": "echo \"(no lint)\"",
|
|
23
|
+
"typecheck": "tsc -p tsconfig.json --noEmit"
|
|
24
|
+
},
|
|
25
|
+
"devDependencies": {
|
|
26
|
+
"@loopflowhq/tsconfig": "*",
|
|
27
|
+
"@types/node": "^22.10.0",
|
|
28
|
+
"typescript": "^5.7.0"
|
|
29
|
+
}
|
|
30
|
+
}
|