@itsflower/cli 0.1.1 → 0.1.3

package/commands/flower.md

@@ -0,0 +1,5 @@
+# flower workflow
+
+Start the `flower` workflow for the following request:
+
+> $DESCRIPTION

package/dist/main.js

@@ -2,10 +2,35 @@
 
 // src/main.ts
 import { defineCommand, runMain } from "citty";
-import { mkdir, readdir, readFile, writeFile } from "fs/promises";
+import { access, mkdir, readdir, readFile, writeFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
+import { homedir } from "os";
 import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function copyDirRecursive(src, dest) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir(src, { withFileTypes: true });
+  const copied = [];
+  for (const entry of entries) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copied.push(...await copyDirRecursive(srcPath, destPath));
+    } else {
+      await writeFile(destPath, await readFile(srcPath));
+      copied.push(destPath);
+    }
+  }
+  return copied;
+}
 var init = defineCommand({
   meta: {
     name: "init",
@@ -25,13 +50,33 @@ var init = defineCommand({
     for (const file of files) {
       console.log(`  - ${file}`);
     }
+    const crushConfigDir = resolve(homedir(), ".config/crush");
+    const skillSrc = resolve(__dirname, "../skills/flower");
+    const skillDest = resolve(crushConfigDir, "skills/flower");
+    const skillExisted = await exists(skillDest);
+    await copyDirRecursive(skillSrc, skillDest);
+    if (skillExisted) {
+      console.log("Updated existing skill: flower");
+    } else {
+      console.log("Installed skill: flower");
+    }
+    const cmdSrc = resolve(__dirname, "../commands/flower.md");
+    const cmdDest = resolve(crushConfigDir, "commands/flower.md");
+    const cmdExisted = await exists(cmdDest);
+    await mkdir(resolve(crushConfigDir, "commands"), { recursive: true });
+    await writeFile(cmdDest, await readFile(cmdSrc));
+    if (cmdExisted) {
+      console.log("Updated existing command: flower");
+    } else {
+      console.log("Installed command: flower");
+    }
     console.log("Done!");
   }
 });
 var main = defineCommand({
   meta: {
     name: "flower",
-    version: "0.1.1",
+    version: "0.1.3",
     description: "\u{1F338} flower CLI"
   },
   subCommands: {

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@itsflower/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "🌸 flower CLI — scaffold structured development workflows",
-  "type": "module",
-  "license": "MIT",
   "keywords": [
-    "flower",
-    "workflow",
     "cli",
-    "templates"
+    "flower",
+    "templates",
+    "workflow"
   ],
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/itsflower/flower"
@@ -19,16 +18,19 @@
   },
   "files": [
     "dist",
-    "templates"
+    "templates",
+    "skills",
+    "commands"
   ],
+  "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsup src/main.ts --format esm --shims",
     "release": "bun run ../../scripts/release.ts",
-    "prepack": "rm -f templates && cp -r ../../core/templates templates",
-    "postpack": "rm -rf templates && ln -s ../../core/templates templates"
+    "prepack": "npm run build && rm -f templates && cp -r ../../core/templates templates && rm -rf skills && cp -r ../../core/skills skills && rm -rf commands && cp -r ../../core/commands commands",
+    "postpack": "rm -rf templates && ln -s ../../core/templates templates && rm -rf skills commands"
   },
   "dependencies": {
     "citty": "^0.2.1"

package/skills/flower/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: flower
+description: Structured development workflow with 4 phases — clarify, plan, build, and review. Use when the user wants to build a feature end-to-end, fix a bug, or refactor with a structured process, or when they mention "quest", "feature", "task", or "workflow".
+---
+
+## Workflow
+
+```mermaid
+flowchart TD
+    Start([User input]) --> P1[Clarify]
+    P1 --> P2[Plan]
+    P2 -- not feasible --> D1([End - plan.md rejected])
+    P2 -- feasible --> P3[Build]
+    P3 --> P4[Review]
+    P4 --> D2([Done])
+```
+
+## Phases
+
+| #   | Phase   | Reference                                      | When                                                    |
+| --- | ------- | ---------------------------------------------- | ------------------------------------------------------- |
+| 1   | Clarify | [references/clarify.md](references/clarify.md) | User describes a feature, bug, or refactor to build     |
+| 2   | Plan    | [references/plan.md](references/plan.md)       | Interview is complete, requirement.md and plan.md ready |
+| 3   | Build   | [references/build.md](references/build.md)     | All tasks are done, ready for quality gate              |
+| 4   | Review  | [references/review.md](references/review.md)   | All tasks are done, ready for quality gate              |
+
+Load only the reference file for the current phase. Do not read ahead.
+
+## Document Convention
+
+Create a folder `.flower/quests/<datetime>--<short-description>/` when starting a new quest.
+
+- `<datetime>` uses `YYMMDD-HHmm` format — run `date +"%y%m%d-%H%M"` to generate it
+- `<short-description>` is a kebab-case summary generated by the agent (e.g. `add-user-auth`, `fix-login-bug`)
+- Folder contains `requirement.md`, `plan.md`, `journal.md`, and `review.md` based on templates in `.flower/templates/`.
+
+## Rules (**STRICTLY ENFORCED**)
+
+- Print `# Phase <number>: <name>` **once** before each phase. After a phase is complete, **IMMEDIATELY** begin the next phase without asking.
+- One quest at a time — finish or park the current quest before starting another
+- Do not skip phases

package/skills/flower/references/build.md

@@ -0,0 +1,106 @@
+# Phase 3: Build
+
+Execute tasks from `plan.md`, test each one, and log knowledge in the journal.
+
+## Workflow (**STRICTLY ENFORCED**)
+
+```mermaid
+flowchart TD
+    Start[plan.md] --> B1[Execute next task]
+    B1 --> B2[Test / Verify]
+    B2 --> C1{Pass?}
+    C1 -- no --> B3[Fix issue]
+    C1 -- yes --> B4[Mark task done]
+    B3 --> B2
+    B4 --> B5[Log in journal if noteworthy]
+    B5 --> C2{All tasks done?}
+    C2 -- no --> B1
+    C2 -- yes --> B6[Mark plan as completed]
+    B6 --> End([Proceed to Phase 4: Review])
+```
+
+## Input
+
+- `requirement.md`
+- `plan.md` with `status: in-progress`
+
+## Steps
+
+### Execute task
+
+For each task in plan order:
+
+- Read the task's Description, AC, and Approach
+- Investigate relevant code before changing it
+- Implement following codebase conventions
+- One logical change per task, as scoped in the plan
+
+**Scale guidance:**
+
+| Complexity   | Investigation       | Implementation          | Testing                  |
+| ------------ | ------------------- | ----------------------- | ------------------------ |
+| **Trivial**  | Quick scan          | Direct change           | Spot check               |
+| **Standard** | Read related files  | Follow approach in plan | Related test suite       |
+| **Complex**  | Deep codebase study | Incremental changes     | Full test suite + manual |
+
+### Test / Verify
+
+- Run relevant tests — unit, integration, or manual as appropriate
+- Verify every AC for this task passes
+- If tests fail → fix and re-verify; do not move on
+- If unrelated tests were already failing → note in journal, do not fix
+
+### Mark task done
+
+Check the task checkbox in plan: `- [ ]` → `- [x]`
+
+### Log in journal
+
+Template: `.flower/templates/journal.md`
+
+Only when something noteworthy happened. Skip if plan was followed exactly.
+
+| Log this             | Example                                                      |
+| -------------------- | ------------------------------------------------------------ |
+| Deviation from plan  | "Used library X instead of Y because Y doesn't support Z"    |
+| Non-obvious decision | "Chose eager loading — dataset is always small"              |
+| Problem & resolution | "Circular dep between A and B — extracted C"                 |
+| Discovery            | "Found existing utility that handles 80% — reused it"        |
+| New task added       | "Added task 4b: migrate old data — discovered during task 4" |
+
+Do **not** log: routine implementation, standard debugging, info already in commits.
+
+**Entry format:**
+
+```markdown
+### [Short actionable title]
+
+- **tags**: [comma-separated domain keywords]
+- **scope**: [global | project:<name>]
+- **context**: [What was being worked on]
+- **insight**: [The decision, discovery, or deviation — focus on WHY]
+```
+
+Create journal file on first entry from template.
+
+### Mark plan as completed
+
+After all tasks are done, verify:
+
+- [ ] All task checkboxes checked
+- [ ] All task ACs verified
+- [ ] All tests pass (full relevant test suite)
+- [ ] No unintended side effects
+- [ ] Journal captures all deviations
+- [ ] Any tasks added during build are also completed
+
+If gaps exist → fix before proceeding. Then set `status: completed` in plan frontmatter.
+
+## Rules
+
+- **Never skip testing** — every task verified before marking done
+- **Don't change task scope** — update the plan first, note in journal
+- **Add, don't expand** — new work = new task in the plan
+- **Follow plan order** — respect dependencies; only skip ahead when blocked
+- **Resumable state** — plan shows exactly where to resume (next unchecked task)
+- **Don't fix unrelated issues** — note in journal for a future quest

package/skills/flower/references/clarify.md

@@ -0,0 +1,83 @@
+# Phase 1: Clarify
+
+Clarify user requirements, clearly describing WHAT and WHY, **not** HOW.
+
+## Workflow (**STRICTLY ENFORCED**)
+
+```mermaid
+flowchart TD
+    Start([User input]) --> C1[Analyze]
+    C1 --> C2[Research]
+    C2 --> C3{Ambiguities resolved?}
+    C3 -- No --> C4[Ask for clarification]
+    C4 --> C1
+    C3 -- Yes --> C5[Create `requirement.md`]
+    C5 --> End([Proceed to Phase 2: Plan])
+```
+
+## Steps
+
+### Analyze
+
+Read user input word by word. Extract:
+
+- **Codebase keywords** → file names, modules, functions, endpoints, components mentioned — feed into codebase exploration
+- **Technology keywords** → libraries, frameworks, languages, tools, APIs mentioned — feed into documentation lookup
+- **Intent** → feature, bug fix, refactor, or enhancement
+- **Constraints** → explicit or implicit limitations
+- **Ambiguities** → anything with multiple interpretations — feed into clarification questions
+
+### Research
+
+Use extracted keywords to investigate before asking:
+
+- **Codebase** → grep, glob, read files, `repomix` — understand existing code, patterns, architecture
+- **Technology** → use MCPs (`context7`, ...), fetch - understand relevant docs for mentioned technologies
+- **External**: look up APIs, standards, or domain concepts the human referenced
+
+### Ask for clarification
+
+Only if ambiguities remain after research:
+
+| Rule            | Detail                                                                                |
+| --------------- | ------------------------------------------------------------------------------------- |
+| Provide options | Offer choices, not open-ended questions. E.g., "(a) partial, (b) exact, or (c) both?" |
+| Batch questions | Group related questions. Max ~5 per round.                                            |
+| Be specific     | Reference concrete code, files, or behaviors.                                         |
+| Easy to answer  | Human should answer in a few words or by picking an option.                           |
+| Show research   | Share what you found to give context to your question.                                |
+
+After each response, restart: analyze → research based on new info → evaluate remaining ambiguities, gaps.
+
+### Create `requirement.md`
+
+Template in `.flower/templates/requirement.md`.
+
+| Section                     | Content                                                             |
+| --------------------------- | ------------------------------------------------------------------- |
+| Problem                     | Who is affected, when, what goes wrong. 2–5 bullets. No solutions.  |
+| User Stories                | "As a [user], I want [action] so that [benefit]"                    |
+| Goals                       | Verifiable outcomes — each yes/no checkable                         |
+| Non-Goals                   | Explicitly excluded — anything someone might assume is in scope     |
+| Acceptance Criteria         | Given/When/Then — pass/fail testable, no subjective judgment        |
+| Constraints & Prerequisites | Hard limits (unchangeable) + external requirements for this feature |
+| Glossary                    | Domain-specific terms only. Skip if self-explanatory.               |
+
+## Validate
+
+- [ ] Every goal is concrete and verifiable
+- [ ] Every goal has at least one acceptance criterion
+- [ ] Scope boundaries are unambiguous
+- [ ] All ambiguities from Q&A are resolved in the document — none deferred
+- [ ] Constraints are realistic and compatible with each other
+
+## Rules
+
+- **Read before asking** — detect keywords and research the codebase first; only ask what you cannot answer yourself
+- **Every word matters** — read the human's input thoroughly; do not skim or skip
+- **Options over open-ended** — always provide choices when asking questions
+- **Draft once, draft right** — documents must be accurate and complete on first draft; the Q&A phase exists to ensure this
+- **Problem ≠ solution** — requirement describes what's wrong, not how to fix it
+- **Non-Goals prevent scope creep** — invest effort here
+- **Self-contained but concise** — a reader must understand the problem and success criteria without reading the codebase
+- **No assumptions** — ambiguities must be resolved through research or Q&A, never assumed

package/skills/flower/references/plan.md

@@ -0,0 +1,96 @@
+# Phase 2: Plan
+
+Research HOW to implement `requirement.md` — explore the codebase, study external docs, decide the approach, and produce `plan.md`.
+
+## Workflow (**STRICTLY ENFORCED**)
+
+```mermaid
+flowchart TD
+    Start([requirement.md]) --> P1[Codebase explore]
+    P1 --> P2[Research external]
+    P2 --> C1{Approach decided?}
+    C1 -- no --> P3[Ask for clarification]
+    P3 --> P4[Create plan.md]
+    C1 -- yes --> P4
+    P4 --> End([Proceed to Phase 3: Build])
+```
+
+## Steps
+
+### Codebase explore
+
+Use goals and acceptance criteria from `requirement.md` as search targets:
+
+- **Architecture** — modules, layers, data flow relevant to the requirement
+- **Patterns** — how similar features are implemented; conventions to follow
+- **Reuse** — what already exists vs. what must be built
+
+Tools: grep, glob, read files, `repomix`.
+
+### Research external
+
+For every technology, library, or pattern relevant to the requirement:
+
+- **Docs** — capabilities, limitations, API surface
+- **Best practices** — recommended approaches, common pitfalls
+- **Alternatives** — competing libraries or patterns that solve the same problem
+
+Tools: `context7`, fetch, web search.
+
+### Ask for clarification
+
+When approach is NOT decided — ask. Do not decide alone.
+
+| Trigger                   | What to present                        |
+| ------------------------- | -------------------------------------- |
+| Multiple valid approaches | Each option with pros, cons, tradeoffs |
+| New library or dependency | What it does, why needed, alternatives |
+| Significant tradeoff      | What is gained vs. given up            |
+
+| Rule            | Detail                                                 |
+| --------------- | ------------------------------------------------------ |
+| Provide options | Offer choices with tradeoffs, not open-ended questions |
+| Show research   | Share findings to give context                         |
+| Batch questions | Group related decisions. Max ~5 per round              |
+| Be specific     | Reference concrete code, libraries, or behaviors       |
+
+### Create `plan.md`
+
+Template in `.flower/templates/plan.md`. Set `status: in-progress`.
+
+| Section             | Content                                                             |
+| ------------------- | ------------------------------------------------------------------- |
+| Overview            | 2-3 sentences: what is being built, approach, key technical choices |
+| Technical Decisions | Non-obvious decisions. WHAT, WHY, alternatives considered           |
+| Tasks               | Ordered by dependency. One logical change per task                  |
+| Dependencies        | Internal and external. Skip if none                                 |
+| Risks & Mitigation  | Only risks that would change the plan. Skip if none                 |
+
+Each task must have:
+
+| Field       | Required | Content                                            |
+| ----------- | -------- | -------------------------------------------------- |
+| Description | Yes      | Clear imperative statement                         |
+| AC          | Yes      | Pass/fail verifiable criteria                      |
+| Approach    | Yes      | Concrete steps, files to touch, patterns to follow |
+| Blocked by  | No       | Task dependency                                    |
+
+If no viable approach exists → set `status: rejected`, fill `## Rejection Reason`. End workflow.
+
+## Validate
+
+- [ ] Every requirement goal maps to at least one task
+- [ ] Every acceptance criterion is covered by a task's AC
+- [ ] Tasks ordered by dependency
+- [ ] Each task has AC and Approach
+- [ ] Technical decisions grounded in codebase research
+- [ ] No compound tasks — split any "X and Y"
+
+## Rules
+
+- **Research before deciding** — explore codebase and docs before forming an approach
+- **Surface choices** — when multiple approaches exist, present them with tradeoffs; never pick silently
+- **New deps need approval** — never add a library to the plan without asking
+- **Decisions in the document** — every choice from Q&A must appear in Technical Decisions
+- **One task, one change** — if a description uses "and", split it
+- **Concrete over vague** — Approach must name files, functions, and patterns

package/skills/flower/references/review.md

@@ -0,0 +1,94 @@
+# Phase 4: Review
+
+Quality gate and delivery summary. Verify everything not covered by task-level testing: security, performance, project standards, and overall correctness.
+
+## Workflow (**STRICTLY ENFORCED**)
+
+```mermaid
+flowchart TD
+    Start([plan.md & journal.md]) --> S[Write delivery summary]
+    S --> CL[Run quality checklist]
+    CL --> CF{All checks pass?}
+    CF -- No --> Fix[Fix issues]
+    Fix --> CL
+    CF -- Yes --> Done([Mark review as completed])
+```
+
+## Input
+
+- `plan.md` with `status: completed` (all tasks checked)
+- `journal.md` (if entries exist)
+- Template: `.flower/templates/review.md`
+
+## Steps
+
+1. **Write delivery summary**
+
+   Create `review.md` from the template in the quest directory. Set `status: draft`.
+
+   **Scale guidance**: match depth to the quest's scope.
+
+   | Quest Size | Summary Length | Metrics              | Outcome Detail    |
+   | ---------- | -------------- | -------------------- | ----------------- |
+   | **Small**  | 2-3 sentences  | Skip if not measured | Brief outcome     |
+   | **Medium** | 3-5 sentences  | Key metrics only     | Outcome + context |
+   | **Large**  | 5-8 sentences  | Full metrics         | Detailed outcome  |
+
+   Write the summary covering:
+   - **What was delivered** — concrete deliverables (features, fixes, refactors), not process steps
+   - **Overall outcome** — did it meet the requirement's goals? Any goals partially met or adjusted?
+   - **Key metrics** — lines changed, test coverage delta, performance improvement, or other measurable results (when available and meaningful)
+   - **Notable deviations** — significant differences from the original plan, if any (reference journal for details)
+
+   The summary must be **self-contained** — someone reading only the review doc should understand what was delivered and whether it succeeded, without referring to the requirement, plan, or journal.
+
+2. **Run quality checklist**
+
+   Go through each item systematically. For each: verify → fix if needed → check off.
+   - [ ] **Dead code & unused files removed** — check for commented-out code, unused imports, orphaned files created during implementation, and temporary debug code
+   - [ ] **Project standards followed** — verify code style, file structure, naming conventions, and linting rules match the rest of the codebase
+   - [ ] **No security issues** — scan for hardcoded secrets, SQL injection, XSS, auth bypass, exposed internal errors, and overly permissive permissions
+   - [ ] **Performance acceptable** — check for N+1 queries, unnecessary re-renders, unbounded loops, large payloads, missing pagination, and missing indexes
+   - [ ] **All tests pass** — run the full relevant test suite (not just per-task tests from Phase 2); verify no regressions were introduced
+   - [ ] **Documentation up to date** — README, API docs, inline docs, and config examples reflect the changes (skip if no user-facing docs exist)
+
+   If fixing an issue requires code changes:
+   1. Make the fix
+   2. Re-run the **full checklist** from the top (a fix can introduce new issues)
+   3. Repeat until all items pass cleanly in a single run
+
+3. **Write memories**
+
+   Record knowledge gained during this quest for future retrieval. Each memory entry uses the structured format:
+
+   ```markdown
+   ### [Short actionable title — 5-12 words]
+
+   - **content**: [Detailed explanation with context and examples]
+   - **tags**: [comma-separated domain keywords]
+   - **scope**: [global | project:<name>]
+   ```
+
+   Skip if no meaningful knowledge was gained.
+
+4. **Mark review as completed** → set `status: completed` in frontmatter
+
+## Output
+
+- Completed `review.md` with `status: completed`
+- Summary of delivery shared with the human
+
+## Rules
+
+- **Summary stands alone** — a reader with no context must understand what was delivered and whether it succeeded
+- **Never skip quality checks** — they catch issues that slip through during implementation; rushing here undermines the entire workflow
+- **Full re-run after fixes** — if quality checks reveal issues requiring code changes, re-run the entire checklist afterward; partial re-checks miss cascading problems
+- **Don't gold-plate** — quality checks fix real issues, they do not refactor working code or add enhancements beyond the quest's scope
+- **Reference, don't repeat** — the summary may reference the plan or journal for details, but must not require them to be understood
+
+## Status Lifecycle
+
+| Status      | Meaning                                 |
+| ----------- | --------------------------------------- |
+| `draft`     | Initial creation, summary being written |
+| `completed` | Quality checks passed, quest done       |