@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.
@@ -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
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,6 @@
1
+ export type InstallOptions = {
2
+ cwd: string;
3
+ now?: Date;
4
+ version: string;
5
+ };
6
+ export declare function installAgentPack(opts: InstallOptions): Promise<void>;
@@ -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
+ }