farmwork 1.4.0 → 1.4.5

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/src/init.js CHANGED
@@ -13,15 +13,9 @@ function detectPackageJson() {
13
13
  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
14
14
  return {
15
15
  scripts: pkg.scripts || {},
16
- hasStorybook: !!(
17
- pkg.devDependencies?.storybook ||
18
- pkg.dependencies?.storybook ||
19
- pkg.devDependencies?.["@storybook/react"] ||
20
- pkg.scripts?.storybook
21
- ),
22
16
  };
23
17
  } catch {
24
- return { scripts: {}, hasStorybook: false };
18
+ return { scripts: {} };
25
19
  }
26
20
  }
27
21
 
@@ -72,12 +66,6 @@ const QUESTIONS = [
72
66
  return `${pm} run lint`;
73
67
  },
74
68
  },
75
- {
76
- type: "confirm",
77
- name: "includeStorybook",
78
- message: "🐄 Include Storybook support?",
79
- default: () => detectPackageJson().hasStorybook,
80
- },
81
69
  {
82
70
  type: "confirm",
83
71
  name: "includeI18n",
@@ -86,35 +74,6 @@ const QUESTIONS = [
86
74
  },
87
75
  ];
88
76
 
89
- const STORYBOOK_QUESTIONS = [
90
- {
91
- type: "input",
92
- name: "storybookUrl",
93
- message: "🌿 Storybook URL:",
94
- default: "storybook.example.com",
95
- },
96
- {
97
- type: "input",
98
- name: "netlifyAuthToken",
99
- message: "🗝️ Netlify Auth Token:",
100
- validate: (input) =>
101
- input.length > 0 || "Auth token is required for deployment",
102
- },
103
- {
104
- type: "input",
105
- name: "netlifySiteId",
106
- message: "🏷️ Netlify Site ID:",
107
- validate: (input) =>
108
- input.length > 0 || "Site ID is required for deployment",
109
- },
110
- {
111
- type: "confirm",
112
- name: "passwordProtect",
113
- message: "🐕 Password protect Storybook?",
114
- default: true,
115
- },
116
- ];
117
-
118
77
  export async function init(options) {
119
78
  const cwd = process.cwd();
120
79
 
@@ -125,10 +84,11 @@ export async function init(options) {
125
84
  const claudeDir = path.join(cwd, ".claude");
126
85
  const farmworkConfig = path.join(cwd, ".farmwork.json");
127
86
  const claudeMd = path.join(cwd, "CLAUDE.md");
87
+ const agentsMd = path.join(cwd, "AGENTS.md");
128
88
 
129
89
  const isAlreadyInstalled =
130
90
  fs.existsSync(claudeDir) &&
131
- (fs.existsSync(farmworkConfig) || fs.existsSync(claudeMd));
91
+ (fs.existsSync(farmworkConfig) || fs.existsSync(claudeMd) || fs.existsSync(agentsMd));
132
92
 
133
93
  if (isAlreadyInstalled && !options.force) {
134
94
  farmTerm.warn("Farmwork is already installed in this project!");
@@ -138,6 +98,7 @@ export async function init(options) {
138
98
  farmTerm.gray(" Detected:\n");
139
99
  if (fs.existsSync(claudeDir)) farmTerm.gray(" • .claude/ directory\n");
140
100
  if (fs.existsSync(claudeMd)) farmTerm.gray(" • CLAUDE.md\n");
101
+ if (fs.existsSync(agentsMd)) farmTerm.gray(" • AGENTS.md\n");
141
102
  if (fs.existsSync(farmworkConfig)) farmTerm.gray(" • .farmwork.json\n");
142
103
  farmTerm.nl();
143
104
 
@@ -189,27 +150,6 @@ export async function init(options) {
189
150
 
190
151
  const answers = await inquirer.prompt(QUESTIONS);
191
152
 
192
- // Storybook configuration
193
- if (answers.includeStorybook) {
194
- farmTerm.nl();
195
- farmTerm.section("Storybook Deployment", "🐄");
196
- farmTerm.gray(
197
- " We recommend deploying Storybook to Netlify with password protection.\n",
198
- );
199
- farmTerm.gray(
200
- " This keeps your component docs private but accessible to your team.\n\n",
201
- );
202
-
203
- const storybookAnswers = await inquirer.prompt(STORYBOOK_QUESTIONS);
204
- Object.assign(answers, storybookAnswers);
205
-
206
- if (answers.passwordProtect) {
207
- farmTerm.nl();
208
- farmTerm.warn("Remember to enable password protection in Netlify:");
209
- farmTerm.gray(" Site settings → Access control → Password protection\n");
210
- }
211
- }
212
-
213
153
  // Check for existing files
214
154
  const existingFiles = [];
215
155
  const filesToCheck = [
@@ -218,6 +158,11 @@ export async function init(options) {
218
158
  name: "CLAUDE.md",
219
159
  backup: "OLD_CLAUDE.md",
220
160
  },
161
+ {
162
+ path: path.join(cwd, "AGENTS.md"),
163
+ name: "AGENTS.md",
164
+ backup: "OLD_AGENTS.md",
165
+ },
221
166
  {
222
167
  path: path.join(cwd, "justfile"),
223
168
  name: "justfile",
@@ -331,6 +276,7 @@ export async function init(options) {
331
276
  },
332
277
  },
333
278
  { name: "Planting CLAUDE.md", fn: () => createClaudeMd(cwd, answers) },
279
+ { name: "Growing AGENTS.md", fn: () => createAgentsMd(cwd, answers) },
334
280
  {
335
281
  name: "Building FARMHOUSE.md",
336
282
  fn: () => createFarmhouseMd(cwd, answers),
@@ -416,8 +362,8 @@ export async function init(options) {
416
362
  // bd init might fail if already initialized
417
363
  }
418
364
 
419
- // Clean up beads-generated files
420
- const beadsAgentFiles = ["AGENTS.md", "@AGENTS.md"];
365
+ // Clean up beads-generated files (only @AGENTS.md, we create our own AGENTS.md)
366
+ const beadsAgentFiles = ["@AGENTS.md"];
421
367
  for (const file of beadsAgentFiles) {
422
368
  try {
423
369
  await fs.remove(path.join(cwd, file));
@@ -443,6 +389,7 @@ export async function init(options) {
443
389
  ".claude/commands/",
444
390
  ".claude/agents/",
445
391
  "CLAUDE.md",
392
+ "AGENTS.md",
446
393
  "justfile",
447
394
  ".farmwork.json",
448
395
  ],
@@ -591,7 +538,8 @@ Run these in order for a complete development cycle:
591
538
 
592
539
  | Phrase | Action |
593
540
  |--------|--------|
594
- | **go to production** | UX production check: update ONBOARDING.md, USER_GUIDE.md, audit CORE_LOOP.md changes |
541
+ | **setup office** | Interactive guided setup: GREENFIELD vision, strategy, optional ONBOARDING and USER_GUIDE |
542
+ | **go to production** | Production check: update BROWNFIELD.md, check GREENFIELD alignment, note doc impacts |
595
543
 
596
544
  ---
597
545
 
@@ -605,10 +553,10 @@ Run these in order for a complete development cycle:
605
553
  **count the herd** (Full Audit Cycle)
606
554
  Runs all inspection agents in parallel, then dry run quality gates. No push.
607
555
 
608
- 1. **Code Review & Cleanup** - \`code-reviewer\` + \`unused-code-cleaner\`
609
- 2. **Performance Audit** - \`performance-auditor\`, updates \`_AUDIT/PERFORMANCE.md\`
610
- 3. **Security Audit** - \`security-auditor\` for OWASP Top 10, updates \`_AUDIT/SECURITY.md\`
611
- 4. **Code Quality** - \`code-smell-auditor\` for DRY violations, updates \`_AUDIT/CODE_QUALITY.md\`
556
+ 1. **Code Quality** - \`code-quality\` for review + smells, updates \`_AUDIT/CODE_QUALITY.md\`
557
+ 2. **Code Cleanup** - \`code-cleaner\` for dead code + comments
558
+ 3. **Performance Audit** - \`performance-auditor\`, updates \`_AUDIT/PERFORMANCE.md\`
559
+ 4. **Security Audit** - \`security-auditor\` for OWASP Top 10, updates \`_AUDIT/SECURITY.md\`
612
560
  5. **Accessibility** - \`accessibility-auditor\` for WCAG 2.1, updates \`_AUDIT/ACCESSIBILITY.md\`
613
561
  6. **Dry Run** - lint, tests, build (but NOT commit/push)
614
562
  7. **Summary Report** - Consolidate findings, ask user next steps
@@ -691,55 +639,117 @@ Runs all inspection agents in parallel, then dry run quality gates. No push.
691
639
 
692
640
  ### Office Phrase Details
693
641
 
642
+ **setup office**
643
+
644
+ Interactive guided setup experience for the _OFFICE/ documents.
645
+
646
+ 1. **Welcome & Context**
647
+ - Display: "Let's set up your product office. I'll guide you through defining your vision and documentation."
648
+ - Check if _OFFICE/ files already exist
649
+ - If existing files found, ask: "Office files already exist. Would you like to update them or start fresh?"
650
+
651
+ 2. **GREENFIELD.md Setup (Required)**
652
+ - Spawn \`strategy-agent\` for interactive setup
653
+ - Ask questions in sequence:
654
+ a. "What's your project name?" (pre-fill from .farmwork.json if available)
655
+ b. "In one sentence, what is this product?"
656
+ c. "What problem does it solve for users?"
657
+ d. "What's the main thing users DO in your app?" (Core action)
658
+ e. "What's stopping users from succeeding?" (Blockers)
659
+ f. "What motivates users to keep using it?" (Motivation)
660
+ - Save answers to GREENFIELD.md
661
+ - Report: "Vision documented in GREENFIELD.md"
662
+
663
+ 3. **Strategy Refinement (Optional)**
664
+ - Ask: "Would you like to define strategic pillars? (y/n)"
665
+ - If yes, ask for 2-3 key principles that guide decisions
666
+ - Add to GREENFIELD.md Strategic Pillars section
667
+
668
+ 4. **ONBOARDING.md Setup (Optional)**
669
+ - Ask: "Does your app have onboarding elements to document? (y/n)"
670
+ - If yes, spawn \`onboarding-agent\` to:
671
+ a. Scan codebase for existing onboarding elements
672
+ b. Ask about welcome experience
673
+ c. Ask about guided tours or tooltips
674
+ d. Document findings in ONBOARDING.md
675
+ - If no, keep placeholder ONBOARDING.md
676
+
677
+ 5. **USER_GUIDE.md Setup (Optional)**
678
+ - Ask: "Would you like to set up user documentation now? (y/n)"
679
+ - If yes, spawn \`user-guide-agent\` to:
680
+ a. Scan codebase for features
681
+ b. Ask about main features to document
682
+ c. Create Quick Start section
683
+ d. Document features in USER_GUIDE.md
684
+ - If no, keep placeholder USER_GUIDE.md
685
+
686
+ 6. **Summary Report**
687
+ \`\`\`
688
+ ## Office Setup Complete
689
+
690
+ ### Documents Created/Updated
691
+ - GREENFIELD.md: [Complete/Updated]
692
+ - BROWNFIELD.md: [Created - will populate on "go to production"]
693
+ - ONBOARDING.md: [Complete/Skipped]
694
+ - USER_GUIDE.md: [Complete/Skipped]
695
+
696
+ ### Next Steps
697
+ - Use "go to production" to update BROWNFIELD.md with implemented features
698
+ - Run /push to commit your office documents
699
+ \`\`\`
700
+
701
+ ---
702
+
694
703
  **go to production**
695
704
 
696
705
  Production readiness check from a user experience perspective. Separate from "close the farm" (which handles code quality/push).
697
706
 
698
- 1. **Update ONBOARDING.md**
699
- - Spawn \`onboarding-agent\` to scan for onboarding elements
700
- - Check for incomplete or missing onboarding flows
707
+ 1. **Update BROWNFIELD.md**
708
+ - Spawn \`brownfield-agent\` to scan for implemented features
709
+ - Document any new features added since last production
710
+ - Document any features removed
711
+ - Update Production History table
701
712
  - Update Last Updated date
702
- - Add changelog entry if changes found
703
713
 
704
- 2. **Update USER_GUIDE.md**
705
- - Spawn \`user-guide-agent\` to scan for undocumented features
706
- - Check for placeholder text or incomplete sections
707
- - Update feature count
708
- - Add changelog entry if changes found
714
+ 2. **Check for Document Impacts**
715
+ - Scan changes against USER_GUIDE.md
716
+ - List any features that need USER_GUIDE updates
717
+ - Scan changes against ONBOARDING.md
718
+ - List any onboarding elements that need updates
709
719
 
710
- 3. **Audit CORE_LOOP.md**
711
- - Spawn \`strategy-agent\` to check if CORE_LOOP.md has changed since last production check
712
- - If changed, add audit trail entry to Strategy Changelog
713
- - Report strategy evolution summary
720
+ 3. **Check GREENFIELD Alignment**
721
+ - Spawn \`strategy-agent\` to compare BROWNFIELD against GREENFIELD
722
+ - Ask user: "Do you see any misalignment between your vision (GREENFIELD) and what's implemented (BROWNFIELD)?"
723
+ - If misalignment reported, add to Strategy Changelog
714
724
 
715
725
  4. **Generate Production Readiness Report**
716
726
  \`\`\`
717
- ## Production Readiness: User Experience
727
+ ## Production Readiness: Implementation Check
718
728
 
719
- ### Strategy Status
729
+ ### BROWNFIELD Status
720
730
  - Last Updated: YYYY-MM-DD
721
- - Changes Since Last Deploy: Yes/No
722
- - Confidence: High/Medium/Low
731
+ - New Features: X added
732
+ - Removed Features: X removed
733
+ - Modified Features: X changed
723
734
 
724
- ### Onboarding Status
725
- - Elements: X documented
726
- - Gaps: X identified
727
- - Empty States: X complete
735
+ ### Documentation Impact
736
+ - USER_GUIDE.md needs updates: [list or "None"]
737
+ - ONBOARDING.md needs updates: [list or "None"]
728
738
 
729
- ### Documentation Status
730
- - Features Documented: X
731
- - Quick Start: Complete/Incomplete
732
- - FAQ: X entries
739
+ ### Strategy Alignment
740
+ - GREENFIELD vision: [summary]
741
+ - BROWNFIELD reality: [summary]
742
+ - Alignment: High/Medium/Low
733
743
 
734
744
  ### Recommendation
735
745
  [Ready for production / Needs attention: ...]
736
746
  \`\`\`
737
747
 
738
748
  5. **Ask for Confirmation**
739
- - "UX production check complete. Ready to proceed with deployment?"
749
+ - "Production check complete. Ready to proceed with deployment?"
740
750
  - Wait for user confirmation before any further action
741
751
 
742
- **Note:** This phrase focuses on UX readiness. Use "close the farm" for code quality gates and pushing to remote.
752
+ **Note:** This phrase focuses on implementation status and alignment. Use "close the farm" for code quality gates and pushing to remote.
743
753
 
744
754
  ---
745
755
 
@@ -790,6 +800,365 @@ ${answers.buildCommand} # Verify compilation
790
800
  await fs.writeFile(path.join(cwd, "CLAUDE.md"), content);
791
801
  }
792
802
 
803
+ async function createAgentsMd(cwd, answers) {
804
+ const content = `# ${answers.projectName}
805
+
806
+ > This document provides guidance for AI coding assistants working on this project.
807
+ > It defines workflows, phrase commands, and project conventions that help maintain
808
+ > code quality and consistent development practices.
809
+
810
+ ---
811
+
812
+ ## MANDATORY: Issue-First Workflow
813
+
814
+ **ALWAYS create beads issues BEFORE starting work.** This ensures full visibility and tracking.
815
+
816
+ ### Single Task
817
+ 1. Create issue: \`bd create "Task description" -t bug|feature|task -p 0-4\`
818
+ 2. Claim it: \`bd update <id> --status in_progress\`
819
+ 3. Do the work
820
+ 4. Close it: \`bd close <id> --reason "What was done"\`
821
+
822
+ ### Multiple Tasks
823
+ When given multiple tasks, **log ALL of them first** before starting:
824
+ 1. Create all issues upfront
825
+ 2. Show what's queued: \`bd list --status open\`
826
+ 3. Work through them one by one
827
+ 4. Close each issue when complete
828
+
829
+ **NO EXCEPTIONS**: Every task gets an issue.
830
+
831
+ ---
832
+
833
+ ## Phrase Commands
834
+
835
+ These are phrase triggers. Most activate when the phrase is the **entire message**.
836
+
837
+ ---
838
+
839
+ ### Farmwork Phrases (Development Workflow)
840
+
841
+ Run these in order for a complete development cycle:
842
+
843
+ | Phrase | Action |
844
+ |--------|--------|
845
+ | **open the farm** | Audit systems, update \`_AUDIT/FARMHOUSE.md\` with current metrics |
846
+ | **count the herd** | Full inspection + dry run: code review, cleanup, performance, security, code quality, accessibility |
847
+ | **go to market** | i18n scan + accessibility audit for missing translations and a11y issues |
848
+ | **close the farm** | Execute commit and push workflow (lint, test, build, commit, push) |
849
+
850
+ ---
851
+
852
+ ### Plan Phrases
853
+
854
+ | Phrase | Action |
855
+ |--------|--------|
856
+ | **make a plan for...** | Investigate codebase, create plan, save to \`_PLANS/*.md\` |
857
+ | **let's implement...** | Load plan from \`_PLANS/*.md\`, create Epic + issues, confirm, start work |
858
+
859
+ ---
860
+
861
+ ### Idea Phrases (Pre-Plan Stage)
862
+
863
+ | Phrase | Action |
864
+ |--------|--------|
865
+ | **I have an idea for...** | Add new idea to \`_AUDIT/GARDEN.md\` (title, description, bullets) |
866
+ | **let's plan this idea...** | Graduate idea from GARDEN → create plan in \`_PLANS/\` |
867
+ | **I dont want to do this idea...** | Reject idea → move from GARDEN to COMPOST |
868
+ | **remove this feature...** | Archive feature idea to COMPOST |
869
+ | **compost this...** | Move idea from GARDEN to COMPOST |
870
+ | **water the garden** | Generate 10 new ideas based on existing GARDEN and COMPOST |
871
+
872
+ ---
873
+
874
+ ### Research Phrases (Pre-Plan Stage)
875
+
876
+ | Phrase | Action |
877
+ |--------|--------|
878
+ | **let's research...** | Create or update research document in \`_RESEARCH/\` |
879
+ | **update research on...** | Update existing research document with fresh findings |
880
+ | **show research on...** | Display summary of existing research document |
881
+
882
+ ---
883
+
884
+ ### Office Phrases (Product Strategy & UX)
885
+
886
+ | Phrase | Action |
887
+ |--------|--------|
888
+ | **setup office** | Interactive guided setup: GREENFIELD vision, strategy, optional ONBOARDING and USER_GUIDE |
889
+ | **go to production** | Production check: update BROWNFIELD.md, check GREENFIELD alignment, note doc impacts |
890
+
891
+ ---
892
+
893
+ ### Farmwork Phrase Details
894
+
895
+ **open the farm**
896
+ 1. Launch \`the-farmer\` agent to audit all systems
897
+ 2. Run \`bd list --status closed | wc -l\` to get total completed issues
898
+ 3. Updates \`_AUDIT/FARMHOUSE.md\` with current metrics
899
+
900
+ **count the herd** (Full Audit Cycle)
901
+ Runs all inspection agents in parallel, then dry run quality gates. No push.
902
+
903
+ 1. **Code Quality** - \`code-quality\` for review + smells, updates \`_AUDIT/CODE_QUALITY.md\`
904
+ 2. **Code Cleanup** - \`code-cleaner\` for dead code + comments
905
+ 3. **Performance Audit** - \`performance-auditor\`, updates \`_AUDIT/PERFORMANCE.md\`
906
+ 4. **Security Audit** - \`security-auditor\` for OWASP Top 10, updates \`_AUDIT/SECURITY.md\`
907
+ 5. **Accessibility** - \`accessibility-auditor\` for WCAG 2.1, updates \`_AUDIT/ACCESSIBILITY.md\`
908
+ 6. **Dry Run** - lint, tests, build (but NOT commit/push)
909
+ 7. **Summary Report** - Consolidate findings, ask user next steps
910
+
911
+ **go to market**
912
+ 1. Scan for hardcoded text not using i18n
913
+ 2. Launch \`i18n-locale-translator\` agent
914
+ 3. Launch \`accessibility-auditor\` for WCAG 2.1 compliance
915
+ 4. Updates \`_AUDIT/ACCESSIBILITY.md\`
916
+
917
+ **close the farm**
918
+ - Execute the commit and push workflow immediately
919
+
920
+ ---
921
+
922
+ ### Idea Phrase Details
923
+
924
+ **I have an idea for...**
925
+ 1. Launch \`idea-gardener\` agent
926
+ 2. Parse idea title from user input
927
+ 3. Ask for short description and bullet points
928
+ 4. Add to \`_AUDIT/GARDEN.md\` under ## Ideas section
929
+
930
+ **let's plan this idea...**
931
+ 1. Launch \`idea-gardener\` agent
932
+ 2. Find the idea in GARDEN.md
933
+ 3. Create plan in \`_PLANS/\` using planning mode
934
+ 4. Move to "Graduated to Plans" table
935
+ 5. Remove from ## Ideas section
936
+
937
+ **compost this...** / **I dont want to do this idea...**
938
+ 1. Launch \`idea-gardener\` agent
939
+ 2. Find idea in GARDEN.md (or accept new rejection)
940
+ 3. Ask for rejection reason
941
+ 4. Add to \`_AUDIT/COMPOST.md\` with reason
942
+ 5. Remove from GARDEN.md if it was there
943
+
944
+ **water the garden**
945
+ 1. Launch \`idea-gardener\` agent
946
+ 2. Read \`_AUDIT/GARDEN.md\` to understand existing ideas and themes
947
+ 3. Read \`_AUDIT/COMPOST.md\` to understand what didn't work and why
948
+ 4. Generate 10 new, creative ideas that:
949
+ - Build on or extend existing garden ideas
950
+ - Avoid patterns that led to composted ideas
951
+ - Consider the project's direction and goals
952
+ 5. Present ideas as a numbered list with title and one-line description
953
+ 6. Ask user: "Which ideas would you like to plant? (enter numbers, e.g., 1, 3, 5)"
954
+ 7. For selected ideas, add each to GARDEN.md with today's planted date
955
+
956
+ ---
957
+
958
+ ### Research Phrase Details
959
+
960
+ **let's research...**
961
+ 1. Launch \`researcher\` agent
962
+ 2. Parse research topic from user input
963
+ 3. Check for existing research in \`_RESEARCH/\`
964
+ 4. Spawn parallel subagents for:
965
+ - Documentation finder (official docs, API refs)
966
+ - Security researcher (CVEs, known issues)
967
+ - Tech stack analyzer (dependencies, compatibility)
968
+ - Community researcher (gotchas, discussions)
969
+ 5. Consolidate findings into \`_RESEARCH/[TOPIC_NAME].md\`
970
+ 6. Display summary and suggest next steps
971
+
972
+ **update research on...**
973
+ 1. Launch \`researcher\` agent
974
+ 2. Find existing research document in \`_RESEARCH/\`
975
+ 3. Run targeted research refresh on specified areas
976
+ 4. Merge new findings, mark outdated info with strikethrough
977
+ 5. Update research history and Last Researched date
978
+
979
+ **show research on...**
980
+ 1. Find research document in \`_RESEARCH/\`
981
+ 2. Display summary of key findings, risks, confidence level
982
+ 3. Suggest refresh if research is aging (15+ days) or stale (30+ days)
983
+
984
+ ---
985
+
986
+ ### Office Phrase Details
987
+
988
+ **setup office**
989
+
990
+ Interactive guided setup experience for the _OFFICE/ documents.
991
+
992
+ 1. **Welcome & Context**
993
+ - Display: "Let's set up your product office. I'll guide you through defining your vision and documentation."
994
+ - Check if _OFFICE/ files already exist
995
+ - If existing files found, ask: "Office files already exist. Would you like to update them or start fresh?"
996
+
997
+ 2. **GREENFIELD.md Setup (Required)**
998
+ - Spawn \`strategy-agent\` for interactive setup
999
+ - Ask questions in sequence:
1000
+ a. "What's your project name?" (pre-fill from .farmwork.json if available)
1001
+ b. "In one sentence, what is this product?"
1002
+ c. "What problem does it solve for users?"
1003
+ d. "What's the main thing users DO in your app?" (Core action)
1004
+ e. "What's stopping users from succeeding?" (Blockers)
1005
+ f. "What motivates users to keep using it?" (Motivation)
1006
+ - Save answers to GREENFIELD.md
1007
+ - Report: "Vision documented in GREENFIELD.md"
1008
+
1009
+ 3. **Strategy Refinement (Optional)**
1010
+ - Ask: "Would you like to define strategic pillars? (y/n)"
1011
+ - If yes, ask for 2-3 key principles that guide decisions
1012
+ - Add to GREENFIELD.md Strategic Pillars section
1013
+
1014
+ 4. **ONBOARDING.md Setup (Optional)**
1015
+ - Ask: "Does your app have onboarding elements to document? (y/n)"
1016
+ - If yes, spawn \`onboarding-agent\` to:
1017
+ a. Scan codebase for existing onboarding elements
1018
+ b. Ask about welcome experience
1019
+ c. Ask about guided tours or tooltips
1020
+ d. Document findings in ONBOARDING.md
1021
+ - If no, keep placeholder ONBOARDING.md
1022
+
1023
+ 5. **USER_GUIDE.md Setup (Optional)**
1024
+ - Ask: "Would you like to set up user documentation now? (y/n)"
1025
+ - If yes, spawn \`user-guide-agent\` to:
1026
+ a. Scan codebase for features
1027
+ b. Ask about main features to document
1028
+ c. Create Quick Start section
1029
+ d. Document features in USER_GUIDE.md
1030
+ - If no, keep placeholder USER_GUIDE.md
1031
+
1032
+ 6. **Summary Report**
1033
+ \`\`\`
1034
+ ## Office Setup Complete
1035
+
1036
+ ### Documents Created/Updated
1037
+ - GREENFIELD.md: [Complete/Updated]
1038
+ - BROWNFIELD.md: [Created - will populate on "go to production"]
1039
+ - ONBOARDING.md: [Complete/Skipped]
1040
+ - USER_GUIDE.md: [Complete/Skipped]
1041
+
1042
+ ### Next Steps
1043
+ - Use "go to production" to update BROWNFIELD.md with implemented features
1044
+ - Run /push to commit your office documents
1045
+ \`\`\`
1046
+
1047
+ ---
1048
+
1049
+ **go to production**
1050
+
1051
+ Production readiness check from a user experience perspective. Separate from "close the farm" (which handles code quality/push).
1052
+
1053
+ 1. **Update BROWNFIELD.md**
1054
+ - Spawn \`brownfield-agent\` to scan for implemented features
1055
+ - Document any new features added since last production
1056
+ - Document any features removed
1057
+ - Update Production History table
1058
+ - Update Last Updated date
1059
+
1060
+ 2. **Check for Document Impacts**
1061
+ - Scan changes against USER_GUIDE.md
1062
+ - List any features that need USER_GUIDE updates
1063
+ - Scan changes against ONBOARDING.md
1064
+ - List any onboarding elements that need updates
1065
+
1066
+ 3. **Check GREENFIELD Alignment**
1067
+ - Spawn \`strategy-agent\` to compare BROWNFIELD against GREENFIELD
1068
+ - Ask user: "Do you see any misalignment between your vision (GREENFIELD) and what's implemented (BROWNFIELD)?"
1069
+ - If misalignment reported, add to Strategy Changelog
1070
+
1071
+ 4. **Generate Production Readiness Report**
1072
+ \`\`\`
1073
+ ## Production Readiness: Implementation Check
1074
+
1075
+ ### BROWNFIELD Status
1076
+ - Last Updated: YYYY-MM-DD
1077
+ - New Features: X added
1078
+ - Removed Features: X removed
1079
+ - Modified Features: X changed
1080
+
1081
+ ### Documentation Impact
1082
+ - USER_GUIDE.md needs updates: [list or "None"]
1083
+ - ONBOARDING.md needs updates: [list or "None"]
1084
+
1085
+ ### Strategy Alignment
1086
+ - GREENFIELD vision: [summary]
1087
+ - BROWNFIELD reality: [summary]
1088
+ - Alignment: High/Medium/Low
1089
+
1090
+ ### Recommendation
1091
+ [Ready for production / Needs attention: ...]
1092
+ \`\`\`
1093
+
1094
+ 5. **Ask for Confirmation**
1095
+ - "Production check complete. Ready to proceed with deployment?"
1096
+ - Wait for user confirmation before any further action
1097
+
1098
+ **Note:** This phrase focuses on implementation status and alignment. Use "close the farm" for code quality gates and pushing to remote.
1099
+
1100
+ ---
1101
+
1102
+ ## Planning Protocol
1103
+
1104
+ **IMPORTANT**: When entering a planning phase for any feature, ALL plans MUST:
1105
+
1106
+ ### Step 1: Save Plan to \`_PLANS/\`
1107
+ Before completing the planning phase, the plan MUST be saved to \`_PLANS/<FEATURE_NAME>.md\`:
1108
+ - Use SCREAMING_SNAKE_CASE for filename
1109
+ - Include: overview, technical approach, files to modify, implementation steps, risks
1110
+
1111
+ ### Step 2: Create Implementation Tracking
1112
+ After user approves:
1113
+ 1. Exit the planning phase
1114
+ 2. Create a beads Epic for the feature
1115
+ 3. Create child issues from plan steps
1116
+
1117
+ ### Step 3: Confirm Before Implementation
1118
+ 1. Show the created Epic and issues
1119
+ 2. **Always ask**: "Ready to start implementing?"
1120
+ 3. Wait for explicit user confirmation
1121
+
1122
+ ---
1123
+
1124
+ ## Project Configuration
1125
+
1126
+ - **Test Command:** \`${answers.testCommand}\`
1127
+ - **Build Command:** \`${answers.buildCommand}\`
1128
+ - **Lint Command:** \`${answers.lintCommand}\`
1129
+
1130
+ ---
1131
+
1132
+ ## Tips for AI Assistants
1133
+
1134
+ ### When Working on Features
1135
+ - Always check the justfile: \`just --list\`
1136
+ - Create issues before starting work
1137
+ - Use "make a plan for..." for non-trivial features
1138
+
1139
+ ### Before Committing
1140
+ \`\`\`bash
1141
+ ${answers.lintCommand} # Check code quality
1142
+ ${answers.buildCommand} # Verify compilation
1143
+ \`\`\`
1144
+
1145
+ ---
1146
+
1147
+ ## Directory Structure
1148
+
1149
+ This project uses a structured directory layout for AI-assisted development:
1150
+
1151
+ | Directory | Purpose |
1152
+ |-----------|---------|
1153
+ | \`_AUDIT/\` | Audit documents and health metrics |
1154
+ | \`_PLANS/\` | Feature implementation plans |
1155
+ | \`_RESEARCH/\` | Research documents |
1156
+ | \`_OFFICE/\` | Strategy and UX documentation |
1157
+ `;
1158
+
1159
+ await fs.writeFile(path.join(cwd, "AGENTS.md"), content);
1160
+ }
1161
+
793
1162
  async function createFarmhouseMd(cwd, answers) {
794
1163
  const today = new Date().toISOString().split("T")[0];
795
1164
 
@@ -809,7 +1178,7 @@ async function createFarmhouseMd(cwd, answers) {
809
1178
  | Metric | Count |
810
1179
  |--------|-------|
811
1180
  | Commands | 2 |
812
- | Agents | 15 |
1181
+ | Agents | 13 |
813
1182
  | Office Docs | 3 |
814
1183
  | Research Docs | 0 |
815
1184
  | Justfile Recipes | 11 |
@@ -830,7 +1199,6 @@ All Claude Code commands and agents are documented, phrase triggers are tested a
830
1199
  | Command | Description |
831
1200
  |---------|-------------|
832
1201
  | \`/push\` | Clean, lint, test, build, commit, push, update metrics |
833
- | \`/office\` | Interactive strategy and UX command - updates CORE_LOOP, ONBOARDING, USER_GUIDE |
834
1202
 
835
1203
  ---
836
1204
 
@@ -839,18 +1207,16 @@ All Claude Code commands and agents are documented, phrase triggers are tested a
839
1207
  | Agent | Purpose |
840
1208
  |-------|---------|
841
1209
  | \`the-farmer\` | Audit and update FARMHOUSE.md metrics |
842
- | \`code-reviewer\` | Quality & security code review |
1210
+ | \`code-quality\` | Code review, DRY violations, complexity, naming |
843
1211
  | \`security-auditor\` | OWASP vulnerability scanning |
844
1212
  | \`performance-auditor\` | Performance anti-patterns |
845
- | \`code-smell-auditor\` | DRY violations, complexity, naming |
846
1213
  | \`accessibility-auditor\` | WCAG 2.1 compliance, alt text, contrast |
847
- | \`unused-code-cleaner\` | Detect and remove dead code |
848
- | \`code-cleaner\` | Remove comments and console.logs |
1214
+ | \`code-cleaner\` | Remove dead code, comments, console.logs |
849
1215
  | \`i18n-locale-translator\` | Translate UI text to locales |
850
- | \`storybook-maintainer\` | Create/update Storybook stories |
851
1216
  | \`idea-gardener\` | Manage Idea Garden and Compost |
852
1217
  | \`researcher\` | Systematic research before planning |
853
- | \`strategy-agent\` | Analyze core loop strategy (what/stopping/why) |
1218
+ | \`strategy-agent\` | Analyze GREENFIELD.md vision and strategy (what/stopping/why) |
1219
+ | \`brownfield-agent\` | Track implemented features in BROWNFIELD.md |
854
1220
  | \`onboarding-agent\` | Document onboarding elements (tours, tooltips, modals) |
855
1221
  | \`user-guide-agent\` | Create feature documentation for help docs |
856
1222
 
@@ -894,7 +1260,8 @@ All Claude Code commands and agents are documented, phrase triggers are tested a
894
1260
 
895
1261
  | Phrase | Action |
896
1262
  |--------|--------|
897
- | \`go to production\` | UX production check: update _OFFICE/ docs |
1263
+ | \`setup office\` | Interactive guided setup: GREENFIELD, ONBOARDING, USER_GUIDE |
1264
+ | \`go to production\` | Update BROWNFIELD.md, check alignment, note doc impacts |
898
1265
 
899
1266
  ---
900
1267
 
@@ -1099,42 +1466,65 @@ _No composted ideas yet._
1099
1466
  async function createOfficeDocs(cwd, answers) {
1100
1467
  const today = new Date().toISOString().split("T")[0];
1101
1468
 
1102
- // Create CORE_LOOP.md - Strategy document
1103
- const coreLoopContent = `# Core Loop Strategy
1469
+ // Create GREENFIELD.md - Vision & Strategy document (replaces CORE_LOOP.md)
1470
+ const greenfieldContent = `# Greenfield Vision
1104
1471
 
1105
- > Treat your product like a game. Define what users are doing, what's stopping them, and why they're doing it.
1106
- > This is a living strategy document - update it as your understanding evolves.
1472
+ > Your product vision and strategic direction. Focus on WHAT you're building, not HOW.
1473
+ > This is a living document that adapts as your understanding evolves.
1107
1474
 
1475
+ **Project Name:** ${answers.projectName}
1108
1476
  **Last Updated:** ${today}
1109
1477
  **Status:** Initial setup
1110
1478
  **Confidence:** Low
1111
1479
 
1112
1480
  ---
1113
1481
 
1114
- ## The Three Questions
1482
+ ## Core Idea
1483
+
1484
+ _What is this product in one sentence?_
1485
+
1486
+ [Describe your product's core purpose]
1487
+
1488
+ ---
1489
+
1490
+ ## Problem Being Solved
1491
+
1492
+ _What pain point or need does this address?_
1493
+
1494
+ **The Problem:**
1495
+ [Describe the problem users face]
1496
+
1497
+ **Why It Matters:**
1498
+ [Explain the impact of solving this problem]
1499
+
1500
+ ---
1501
+
1502
+ ## The Game Loop (Strategy)
1503
+
1504
+ > Treat your product like a game. What keeps users engaged?
1115
1505
 
1116
1506
  ### 1. What are they doing?
1117
- _What is the primary action or loop your users engage in?_
1507
+ _The primary action or loop users engage in_
1118
1508
 
1119
- **Current Understanding:**
1120
- [Describe the core user action/loop]
1509
+ **Core Action:**
1510
+ [Describe the main user activity]
1121
1511
 
1122
1512
  ### 2. What's stopping them?
1123
- _What friction, obstacles, or pain points prevent users from succeeding?_
1513
+ _Friction, obstacles, or pain points_
1124
1514
 
1125
1515
  **Current Blockers:**
1126
1516
  - [Blocker 1]
1127
1517
  - [Blocker 2]
1128
1518
 
1129
1519
  ### 3. Why are they doing it?
1130
- _What motivates users? What's the deeper goal or reward?_
1520
+ _Underlying motivation and rewards_
1131
1521
 
1132
1522
  **User Motivation:**
1133
- [Describe the underlying motivation]
1523
+ [Describe what drives users]
1134
1524
 
1135
1525
  ---
1136
1526
 
1137
- ## Core Loop Diagram
1527
+ ## Vision Loop
1138
1528
 
1139
1529
  \`\`\`
1140
1530
  [Entry Point] → [Core Action] → [Reward/Feedback] → [Loop Back]
@@ -1142,21 +1532,144 @@ _What motivates users? What's the deeper goal or reward?_
1142
1532
 
1143
1533
  ---
1144
1534
 
1535
+ ## Strategic Pillars
1536
+
1537
+ _Key principles that guide product decisions_
1538
+
1539
+ 1. **[Pillar 1]** - [Description]
1540
+ 2. **[Pillar 2]** - [Description]
1541
+ 3. **[Pillar 3]** - [Description]
1542
+
1543
+ ---
1544
+
1545
+ ## Success Metrics
1546
+
1547
+ | Metric | Current | Target | Notes |
1548
+ |--------|---------|--------|-------|
1549
+ | [Metric 1] | TBD | [goal] | |
1550
+ | [Metric 2] | TBD | [goal] | |
1551
+
1552
+ ---
1553
+
1145
1554
  ## Strategy Changelog
1146
1555
 
1147
1556
  | Date | Change | Previous | Reason |
1148
1557
  |------|--------|----------|--------|
1149
- | ${today} | Initial strategy setup | - | Created via farmwork init |
1558
+ | ${today} | Initial vision setup | - | Created via farmwork init |
1150
1559
 
1151
1560
  ---
1152
1561
 
1153
1562
  ## Related Documents
1154
1563
 
1564
+ - [BROWNFIELD.md](./_OFFICE/BROWNFIELD.md) - What's already implemented
1155
1565
  - [ONBOARDING.md](./_OFFICE/ONBOARDING.md) - First-time user experience
1156
1566
  - [USER_GUIDE.md](./_OFFICE/USER_GUIDE.md) - Feature documentation
1157
1567
  `;
1158
1568
 
1159
- await fs.writeFile(path.join(cwd, "_OFFICE", "CORE_LOOP.md"), coreLoopContent);
1569
+ await fs.writeFile(path.join(cwd, "_OFFICE", "GREENFIELD.md"), greenfieldContent);
1570
+
1571
+ // Create BROWNFIELD.md - Implementation Status document
1572
+ const brownfieldContent = `# Brownfield Status
1573
+
1574
+ > What's already implemented. Focus on WHAT exists, not HOW it works.
1575
+ > Updated during "go to production" to track solidified features.
1576
+
1577
+ **Last Updated:** ${today}
1578
+ **Status:** Initial setup
1579
+ **Implemented Features:** 0
1580
+
1581
+ ---
1582
+
1583
+ ## Current State
1584
+
1585
+ _High-level summary of what the app currently does_
1586
+
1587
+ [Describe current implementation state]
1588
+
1589
+ ---
1590
+
1591
+ ## Solidified Features
1592
+
1593
+ _Features that are complete and stable_
1594
+
1595
+ <!-- Feature format:
1596
+ ### Feature Name
1597
+ **Status:** Complete | Stable | Production-ready
1598
+ **Added:** YYYY-MM-DD
1599
+
1600
+ Brief description of what this feature does.
1601
+
1602
+ **Capabilities:**
1603
+ - Capability 1
1604
+ - Capability 2
1605
+ -->
1606
+
1607
+ _No features solidified yet._
1608
+
1609
+ ---
1610
+
1611
+ ## Recent Changes
1612
+
1613
+ _Features added or removed in recent production cycles_
1614
+
1615
+ ### Added
1616
+ | Feature | Date | Notes |
1617
+ |---------|------|-------|
1618
+ | | | |
1619
+
1620
+ ### Removed
1621
+ | Feature | Date | Reason |
1622
+ |---------|------|--------|
1623
+ | | | |
1624
+
1625
+ ### Modified
1626
+ | Feature | Date | Change |
1627
+ |---------|------|--------|
1628
+ | | | |
1629
+
1630
+ ---
1631
+
1632
+ ## Workflows
1633
+
1634
+ _User workflows that are implemented_
1635
+
1636
+ <!-- Workflow format:
1637
+ ### Workflow Name
1638
+ 1. Step 1
1639
+ 2. Step 2
1640
+ 3. Step 3
1641
+ -->
1642
+
1643
+ _No workflows documented yet._
1644
+
1645
+ ---
1646
+
1647
+ ## Technical Constraints
1648
+
1649
+ _Implementation decisions that affect future development_
1650
+
1651
+ | Constraint | Reason | Impact |
1652
+ |------------|--------|--------|
1653
+ | | | |
1654
+
1655
+ ---
1656
+
1657
+ ## Production History
1658
+
1659
+ | Date | Version | Changes Summary |
1660
+ |------|---------|-----------------|
1661
+ | ${today} | Initial | Created via farmwork init |
1662
+
1663
+ ---
1664
+
1665
+ ## Related Documents
1666
+
1667
+ - [GREENFIELD.md](./_OFFICE/GREENFIELD.md) - Vision and strategy
1668
+ - [ONBOARDING.md](./_OFFICE/ONBOARDING.md) - First-time user experience
1669
+ - [USER_GUIDE.md](./_OFFICE/USER_GUIDE.md) - Feature documentation
1670
+ `;
1671
+
1672
+ await fs.writeFile(path.join(cwd, "_OFFICE", "BROWNFIELD.md"), brownfieldContent);
1160
1673
 
1161
1674
  // Create ONBOARDING.md - Onboarding tracker
1162
1675
  const onboardingContent = `# User Onboarding
@@ -1232,6 +1745,14 @@ _What users see before they have data_
1232
1745
  | Date | Change | Reason |
1233
1746
  |------|--------|--------|
1234
1747
  | ${today} | Initial onboarding setup | Created via farmwork init |
1748
+
1749
+ ---
1750
+
1751
+ ## Related Documents
1752
+
1753
+ - [GREENFIELD.md](./_OFFICE/GREENFIELD.md) - Vision and strategy
1754
+ - [BROWNFIELD.md](./_OFFICE/BROWNFIELD.md) - What's already implemented
1755
+ - [USER_GUIDE.md](./_OFFICE/USER_GUIDE.md) - Feature documentation
1235
1756
  `;
1236
1757
 
1237
1758
  await fs.writeFile(path.join(cwd, "_OFFICE", "ONBOARDING.md"), onboardingContent);
@@ -1276,7 +1797,7 @@ Brief description of what this feature does.
1276
1797
  **Related:** [Link to related feature]
1277
1798
  -->
1278
1799
 
1279
- _No features documented yet. Run \`/office\` to add features._
1800
+ _No features documented yet. Say "setup office" to add features._
1280
1801
 
1281
1802
  ---
1282
1803
 
@@ -1301,6 +1822,14 @@ _No FAQs yet._
1301
1822
  | Date | Change |
1302
1823
  |------|--------|
1303
1824
  | ${today} | Initial user guide setup |
1825
+
1826
+ ---
1827
+
1828
+ ## Related Documents
1829
+
1830
+ - [GREENFIELD.md](./_OFFICE/GREENFIELD.md) - Vision and strategy
1831
+ - [BROWNFIELD.md](./_OFFICE/BROWNFIELD.md) - What's already implemented
1832
+ - [ONBOARDING.md](./_OFFICE/ONBOARDING.md) - First-time user experience
1304
1833
  `;
1305
1834
 
1306
1835
  await fs.writeFile(path.join(cwd, "_OFFICE", "USER_GUIDE.md"), userGuideContent);
@@ -1480,22 +2009,32 @@ Read all documents in \`_RESEARCH/\` and check their age:
1480
2009
  ### Score: X/10
1481
2010
  \`\`\`
1482
2011
  `,
1483
- "code-reviewer.md": `---
1484
- name: code-reviewer
1485
- description: Review code for quality, security, and maintainability
1486
- tools: Read, Grep, Glob, Bash
2012
+ "code-quality.md": `---
2013
+ name: code-quality
2014
+ description: Review code for quality, maintainability, DRY violations, and code smells
2015
+ tools: Read, Grep, Glob, Edit
1487
2016
  model: opus
1488
2017
  ---
1489
2018
 
1490
- # Code Reviewer Agent
2019
+ # Code Quality Agent
1491
2020
 
1492
- Reviews staged/modified files for:
1493
- - Security vulnerabilities
1494
- - Performance issues
1495
- - Code quality problems
2021
+ Comprehensive code quality review covering:
2022
+
2023
+ ## Code Review
2024
+ - Readability and maintainability
1496
2025
  - Best practice violations
2026
+ - Error handling patterns
2027
+ - API design issues
2028
+
2029
+ ## Code Smells
2030
+ - DRY violations (duplicated code)
2031
+ - Complexity issues (functions > 50 lines, deep nesting)
2032
+ - Naming issues (misleading names, abbreviations)
2033
+ - Magic values (hardcoded numbers/strings)
2034
+ - Technical debt (TODO, FIXME, HACK comments)
1497
2035
 
1498
- Reports findings with severity (CRITICAL, HIGH, MEDIUM, LOW) and remediation steps.
2036
+ Reports findings with severity (CRITICAL, HIGH, MEDIUM, LOW).
2037
+ Updates \`_AUDIT/CODE_QUALITY.md\` with results.
1499
2038
  `,
1500
2039
  "security-auditor.md": `---
1501
2040
  name: security-auditor
@@ -1534,25 +2073,6 @@ Scans for performance anti-patterns:
1534
2073
 
1535
2074
  Reports findings with impact assessment.
1536
2075
  Updates \`_AUDIT/PERFORMANCE.md\` with results.
1537
- `,
1538
- "code-smell-auditor.md": `---
1539
- name: code-smell-auditor
1540
- description: Detect DRY violations, complexity issues, naming problems, and technical debt
1541
- tools: Read, Grep, Glob, Edit
1542
- model: opus
1543
- ---
1544
-
1545
- # Code Smell Auditor Agent
1546
-
1547
- Scans for code quality issues:
1548
- - DRY violations (duplicated code)
1549
- - Complexity issues (functions > 50 lines, deep nesting)
1550
- - Naming issues (misleading names, abbreviations)
1551
- - Magic values (hardcoded numbers/strings)
1552
- - Technical debt (TODO, FIXME, HACK comments)
1553
-
1554
- Reports code health as GOOD / FAIR / NEEDS ATTENTION.
1555
- Updates \`_AUDIT/CODE_QUALITY.md\` with results.
1556
2076
  `,
1557
2077
  "accessibility-auditor.md": `---
1558
2078
  name: accessibility-auditor
@@ -1573,38 +2093,23 @@ Scans for WCAG 2.1 Level AA compliance issues:
1573
2093
 
1574
2094
  Reports findings by severity (CRITICAL, HIGH, MEDIUM, LOW).
1575
2095
  Updates \`_AUDIT/ACCESSIBILITY.md\` with results.
1576
- `,
1577
- "unused-code-cleaner.md": `---
1578
- name: unused-code-cleaner
1579
- description: Detect and remove unused code (imports, functions, variables)
1580
- tools: Read, Write, Edit, Bash, Grep, Glob
1581
- model: opus
1582
- ---
1583
-
1584
- # Unused Code Cleaner Agent
1585
-
1586
- Detects and removes unused code:
1587
- - Unused imports
1588
- - Unused functions and classes
1589
- - Unused variables
1590
- - Dead code paths
1591
- - Console.log statements (optional)
1592
- - Comments (preserves JSDoc)
1593
-
1594
- Use after refactoring, when removing features, or before production deployment.
1595
2096
  `,
1596
2097
  "code-cleaner.md": `---
1597
2098
  name: code-cleaner
1598
- description: Fast removal of comments, console.logs, and debug code while preserving JSDoc
1599
- tools: Read, Edit, Glob, Grep
2099
+ description: Remove dead code, unused imports, comments, and console.logs while preserving JSDoc
2100
+ tools: Read, Write, Edit, Bash, Grep, Glob
1600
2101
  model: opus
1601
2102
  ---
1602
2103
 
1603
2104
  # Code Cleaner Agent
1604
2105
 
1605
- Fast cleanup of TypeScript/JavaScript files:
2106
+ Comprehensive code cleanup for TypeScript/JavaScript files.
1606
2107
 
1607
2108
  ## Removes
2109
+ - Unused imports
2110
+ - Unused functions and classes
2111
+ - Unused variables
2112
+ - Dead code paths
1608
2113
  - Line comments (\`//\`)
1609
2114
  - Block comments (\`/* */\`)
1610
2115
  - \`console.log\` statements
@@ -1612,6 +2117,8 @@ Fast cleanup of TypeScript/JavaScript files:
1612
2117
  ## Preserves
1613
2118
  - JSDoc comments (\`/** */\`)
1614
2119
  - \`console.error\`, \`console.warn\`, \`console.info\`
2120
+
2121
+ Use after refactoring, when removing features, or before production deployment.
1615
2122
  `,
1616
2123
  "i18n-locale-translator.md": `---
1617
2124
  name: i18n-locale-translator
@@ -1629,23 +2136,6 @@ Handles internationalization tasks:
1629
2136
  - Update components to use translation hooks
1630
2137
 
1631
2138
  Use when adding new features or internationalizing existing hardcoded text.
1632
- `,
1633
- "storybook-maintainer.md": `---
1634
- name: storybook-maintainer
1635
- description: Create and update Storybook stories for UI components
1636
- tools: Read, Write, Edit, Glob, Grep
1637
- model: opus
1638
- ---
1639
-
1640
- # Storybook Maintainer Agent
1641
-
1642
- Manages Storybook stories for UI components:
1643
- - Analyze component props and variants
1644
- - Create comprehensive story files
1645
- - Document component usage
1646
- - Add controls for interactive props
1647
-
1648
- Use when adding new components or when existing components change significantly.
1649
2139
  `,
1650
2140
  "idea-gardener.md": `---
1651
2141
  name: idea-gardener
@@ -1963,65 +2453,141 @@ Next steps:
1963
2453
  `,
1964
2454
  "strategy-agent.md": `---
1965
2455
  name: strategy-agent
1966
- description: Analyze and update the core loop strategy - what users do, what stops them, why they do it
2456
+ description: Analyze and update GREENFIELD.md - product vision, core loop strategy, and strategic alignment
1967
2457
  tools: Read, Edit, Glob, Grep, Task
1968
2458
  model: opus
1969
2459
  ---
1970
2460
 
1971
2461
  # Strategy Agent
1972
2462
 
1973
- Maintains \`_OFFICE/CORE_LOOP.md\` - the living strategy document for product thinking.
2463
+ Maintains \`_OFFICE/GREENFIELD.md\` - the living vision and strategy document.
1974
2464
 
1975
2465
  ## Core Responsibility
1976
2466
 
1977
- Treat the product like a game and answer three fundamental questions:
1978
- 1. **What are they doing?** - The primary user action/loop
1979
- 2. **What's stopping them?** - Friction and obstacles
1980
- 3. **Why are they doing it?** - Underlying motivation and rewards
2467
+ Define and refine the product vision focusing on WHAT, not HOW:
2468
+ 1. **Core Idea** - What is this product?
2469
+ 2. **Problem Being Solved** - What pain point does it address?
2470
+ 3. **The Game Loop** - What are they doing / What's stopping them / Why are they doing it
1981
2471
 
1982
2472
  ## Instructions
1983
2473
 
1984
- ### When Invoked via /office
2474
+ ### When Invoked via "setup office"
1985
2475
 
1986
- 1. Read \`_OFFICE/CORE_LOOP.md\` to understand current strategy
1987
- 2. Read the codebase to understand the product (components, routes, features)
1988
- 3. Ask the user probing questions:
1989
- - "What's the main thing users do in your app?"
1990
- - "Where do users get stuck or confused?"
1991
- - "What's the 'aha moment' for users?"
1992
- - "What brings users back?"
1993
- 4. Update CORE_LOOP.md with insights
1994
- 5. Add entry to Strategy Changelog table
2476
+ Interactive setup mode:
2477
+ 1. Ask user for project vision in one sentence
2478
+ 2. Ask about the problem being solved
2479
+ 3. Guide through game loop questions (What/Stopping/Why)
2480
+ 4. Ask about strategic pillars (optional)
2481
+ 5. Create/update GREENFIELD.md with answers
2482
+ 6. Add entry to Strategy Changelog
1995
2483
 
1996
2484
  ### When Checking for Production ("go to production")
1997
2485
 
1998
- 1. Read \`_OFFICE/CORE_LOOP.md\`
1999
- 2. Compare current date to Last Updated date
2000
- 3. If changed since last production push:
2001
- - Summarize strategy changes
2002
- - Add audit entry to changelog
2003
- 4. Report strategy status
2486
+ Alignment check mode:
2487
+ 1. Read \`_OFFICE/GREENFIELD.md\` (vision)
2488
+ 2. Read \`_OFFICE/BROWNFIELD.md\` (implementation)
2489
+ 3. Compare vision against reality
2490
+ 4. Ask user: "Do you see any misalignment between your vision and what's implemented?"
2491
+ 5. If misalignment, document in Strategy Changelog
2492
+ 6. Report alignment status (High/Medium/Low)
2493
+
2494
+ ### Probing Questions for Vision
2495
+
2496
+ - "What is this product in one sentence?"
2497
+ - "What problem does it solve for users?"
2498
+ - "What's the main thing users DO in your app?"
2499
+ - "What prevents users from succeeding?"
2500
+ - "What motivates users to return?"
2501
+ - "What are 2-3 key principles that guide your decisions?"
2004
2502
 
2005
2503
  ## Output Format
2006
2504
 
2007
2505
  \`\`\`
2008
- ## Strategy Analysis
2506
+ ## Vision Analysis
2009
2507
 
2010
- ### Core Loop
2011
- [Describe the identified core loop]
2508
+ ### Core Idea
2509
+ [One-sentence product description]
2012
2510
 
2013
- ### Key Friction Points
2014
- - [Friction 1]
2015
- - [Friction 2]
2511
+ ### Problem
2512
+ [Problem being solved]
2016
2513
 
2017
- ### User Motivation
2018
- [Describe why users engage]
2514
+ ### Game Loop
2515
+ - Action: [What users do]
2516
+ - Blockers: [What stops them]
2517
+ - Motivation: [Why they do it]
2019
2518
 
2020
- ### Recommendations
2021
- - [Recommendation 1]
2022
- - [Recommendation 2]
2519
+ ### Strategic Pillars
2520
+ 1. [Pillar 1]
2521
+ 2. [Pillar 2]
2522
+ 3. [Pillar 3]
2523
+
2524
+ Updated _OFFICE/GREENFIELD.md
2525
+ \`\`\`
2526
+ `,
2527
+ "brownfield-agent.md": `---
2528
+ name: brownfield-agent
2529
+ description: Track implemented features and changes in BROWNFIELD.md during production cycles
2530
+ tools: Read, Edit, Glob, Grep, Task
2531
+ model: opus
2532
+ ---
2533
+
2534
+ # Brownfield Agent
2535
+
2536
+ Maintains \`_OFFICE/BROWNFIELD.md\` - tracking what's actually implemented.
2537
+
2538
+ ## Core Responsibility
2539
+
2540
+ Document the current state of implementation focusing on WHAT exists, not HOW:
2541
+ - Solidified features
2542
+ - Recent additions and removals
2543
+ - User workflows
2544
+ - Technical constraints
2545
+
2546
+ ## Instructions
2547
+
2548
+ ### When Invoked via "go to production"
2549
+
2550
+ 1. Read current \`_OFFICE/BROWNFIELD.md\`
2551
+ 2. Scan the codebase for implemented features:
2552
+ - Check routes, pages, and main components
2553
+ - Look for feature flags or feature directories
2554
+ - Identify user-facing functionality
2555
+ 3. Compare against last production snapshot
2556
+ 4. Document changes:
2557
+ - **Added:** New features since last production
2558
+ - **Removed:** Features that were removed
2559
+ - **Modified:** Significant changes to existing features
2560
+ 5. Update Solidified Features section for stable features
2561
+ 6. Update Production History table
2562
+ 7. Update Last Updated date
2563
+
2564
+ ### When Checking Alignment
2565
+
2566
+ 1. List all solidified features
2567
+ 2. List all documented workflows
2568
+ 3. Compare against GREENFIELD.md vision
2569
+ 4. Identify any gaps or misalignment
2570
+
2571
+ ## Output Format
2023
2572
 
2024
- Updated _OFFICE/CORE_LOOP.md
2573
+ \`\`\`
2574
+ ## Implementation Status
2575
+
2576
+ ### Current Features
2577
+ - Feature A (stable)
2578
+ - Feature B (new)
2579
+ - Feature C (modified)
2580
+
2581
+ ### Changes This Cycle
2582
+ - Added: [list]
2583
+ - Removed: [list]
2584
+ - Modified: [list]
2585
+
2586
+ ### Workflows Documented
2587
+ - Workflow 1: [X steps]
2588
+ - Workflow 2: [Y steps]
2589
+
2590
+ Updated _OFFICE/BROWNFIELD.md
2025
2591
  \`\`\`
2026
2592
  `,
2027
2593
  "onboarding-agent.md": `---
@@ -2047,7 +2613,7 @@ Identify, document, and track all onboarding-related UI elements:
2047
2613
 
2048
2614
  ## Instructions
2049
2615
 
2050
- ### When Invoked via /office
2616
+ ### When Invoked via "setup office"
2051
2617
 
2052
2618
  1. Read \`_OFFICE/ONBOARDING.md\` to understand current state
2053
2619
  2. Scan the codebase for onboarding elements:
@@ -2114,7 +2680,7 @@ Create and maintain user-facing documentation for features:
2114
2680
 
2115
2681
  ## Instructions
2116
2682
 
2117
- ### When Invoked via /office
2683
+ ### When Invoked via "setup office"
2118
2684
 
2119
2685
  1. Read \`_OFFICE/USER_GUIDE.md\` to understand current documentation
2120
2686
  2. Scan the codebase for features:
@@ -2181,28 +2747,10 @@ Updated _OFFICE/USER_GUIDE.md
2181
2747
  async function createCommands(cwd, answers) {
2182
2748
  const pm = answers.packageManager || "npm";
2183
2749
 
2184
- const storybookSteps = answers.includeStorybook
2185
- ? `
2186
-
2187
- ### Step 9: Deploy Storybook to Netlify
2188
-
2189
- Deploy the Storybook documentation site:
2190
- \`\`\`bash
2191
- npx netlify deploy --dir=storybook-static --site=$NETLIFY_STORYBOOK_SITE_ID --prod
2192
- \`\`\`
2193
-
2194
- Note: Requires \`NETLIFY_AUTH_TOKEN\` and \`NETLIFY_STORYBOOK_SITE_ID\` in \`.claude/settings.local.json\`.
2195
- If not configured, skip this step and inform the user to add the env vars.
2196
-
2197
- Storybook URL: https://${answers.storybookUrl || "storybook.example.com"}
2198
- ${answers.passwordProtect ? "**Note:** This Storybook is password protected." : ""}
2199
- `
2200
- : "";
2201
-
2202
2750
  const pushCommand = `---
2203
2751
  description: Clean, stage, lint, test, build, commit, push, and update metrics
2204
2752
  argument-hint: [optional: commit message override]
2205
- allowed-tools: Bash(find:*), Bash(git:*), Bash(${pm}:*), Bash(npx:*)${answers.includeStorybook ? ", Bash(npx netlify:*)" : ""}, Task
2753
+ allowed-tools: Bash(find:*), Bash(git:*), Bash(${pm}:*), Bash(npx:*), Task
2206
2754
  ---
2207
2755
 
2208
2756
  # Push Command
@@ -2257,9 +2805,9 @@ git add -A
2257
2805
 
2258
2806
  Run each check. If any fails, stop and report which check failed:
2259
2807
 
2260
- 1. **Lint**: \`${answers.lintCommand}\`${answers.includeStorybook ? `\n2. **Storybook**: \`${pm} run build-storybook\`` : ""}
2261
- ${answers.includeStorybook ? "3" : "2"}. **Unit Tests**: \`${answers.testCommand}\`
2262
- ${answers.includeStorybook ? "4" : "3"}. **Build**: \`${answers.buildCommand}\`
2808
+ 1. **Lint**: \`${answers.lintCommand}\`
2809
+ 2. **Unit Tests**: \`${answers.testCommand}\`
2810
+ 3. **Build**: \`${answers.buildCommand}\`
2263
2811
 
2264
2812
  ### Step 7: Generate Commit Message
2265
2813
 
@@ -2286,8 +2834,8 @@ Then push to remote:
2286
2834
  \`\`\`bash
2287
2835
  git push
2288
2836
  \`\`\`
2289
- ${storybookSteps}
2290
- ### Step 10: Update Farmhouse Metrics
2837
+
2838
+ ### Step 9: Update Farmhouse Metrics
2291
2839
 
2292
2840
  Run the-farmer agent to update \`_AUDIT/FARMHOUSE.md\` with current metrics:
2293
2841
  - Commands and agents inventory
@@ -2296,12 +2844,12 @@ Run the-farmer agent to update \`_AUDIT/FARMHOUSE.md\` with current metrics:
2296
2844
 
2297
2845
  This keeps the harness documentation in sync with the codebase.
2298
2846
 
2299
- ### Step 11: Report Success
2847
+ ### Step 10: Report Success
2300
2848
 
2301
2849
  Show a summary:
2302
2850
  - Files changed
2303
2851
  - Commit hash
2304
- - Push status${answers.includeStorybook ? "\n- Storybook deploy status (if deployed)" : ""}
2852
+ - Push status
2305
2853
  - Harness metrics updated
2306
2854
  `;
2307
2855
 
@@ -2310,181 +2858,15 @@ Show a summary:
2310
2858
  pushCommand,
2311
2859
  );
2312
2860
 
2313
- // Create /office command
2314
- const officeCommand = `---
2315
- description: Interactive strategy and user experience command - updates CORE_LOOP, ONBOARDING, and USER_GUIDE
2316
- argument-hint: [optional: focus area - strategy|onboarding|guide|all]
2317
- allowed-tools: Read, Edit, Glob, Grep, Task
2318
- ---
2319
-
2320
- # Office Command
2321
-
2322
- Interactive command for product strategy and user experience documentation.
2323
- Updates all three \`_OFFICE/\` documents based on user answers.
2324
-
2325
- ## Usage
2326
-
2327
- \`\`\`
2328
- /office # Run full office check (all areas)
2329
- /office strategy # Focus on core loop strategy
2330
- /office onboarding # Focus on onboarding elements
2331
- /office guide # Focus on user documentation
2332
- \`\`\`
2333
-
2334
- ## Workflow
2335
-
2336
- ### Step 1: Determine Focus Area
2337
-
2338
- If \`$ARGUMENTS\` is provided, focus on that area:
2339
- - \`strategy\` or \`core\` or \`loop\` → Core loop only
2340
- - \`onboarding\` or \`tour\` or \`welcome\` → Onboarding only
2341
- - \`guide\` or \`docs\` or \`help\` → User guide only
2342
- - \`all\` or empty → All three areas
2343
-
2344
- ### Step 2: Run Strategy Analysis (if applicable)
2345
-
2346
- Spawn \`strategy-agent\` subagent to:
2347
- 1. Read current \`_OFFICE/CORE_LOOP.md\`
2348
- 2. Analyze the codebase to understand the product
2349
- 3. Ask user questions about the core loop:
2350
- - "What is the main action users take in your app?"
2351
- - "What prevents users from succeeding?"
2352
- - "What motivates users to return?"
2353
- 4. Update CORE_LOOP.md with findings
2354
- 5. Add changelog entry
2355
-
2356
- ### Step 3: Run Onboarding Analysis (if applicable)
2357
-
2358
- Spawn \`onboarding-agent\` subagent to:
2359
- 1. Read current \`_OFFICE/ONBOARDING.md\`
2360
- 2. Scan codebase for onboarding elements:
2361
- - Tour libraries (react-joyride, shepherd.js, intro.js)
2362
- - Modal/popup components
2363
- - Tooltip implementations
2364
- - Empty state components
2365
- 3. Ask user questions:
2366
- - "What should new users see first?"
2367
- - "What's the key 'aha moment'?"
2368
- - "Any existing tours or tooltips?"
2369
- 4. Update ONBOARDING.md tables
2370
- 5. Add changelog entry
2371
-
2372
- ### Step 4: Run User Guide Analysis (if applicable)
2373
-
2374
- Spawn \`user-guide-agent\` subagent to:
2375
- 1. Read current \`_OFFICE/USER_GUIDE.md\`
2376
- 2. Scan codebase for features:
2377
- - Routes and pages
2378
- - User-facing components
2379
- - Keyboard shortcuts
2380
- 3. Ask user questions:
2381
- - "What are the main features?"
2382
- - "Common user questions?"
2383
- - "Any shortcuts to document?"
2384
- 4. Create/update feature documentation blocks
2385
- 5. Add changelog entry
2386
-
2387
- ### Step 5: Generate Summary Report
2388
-
2389
- Display a summary of all updates:
2390
-
2391
- \`\`\`
2392
- ## Office Update Complete
2393
-
2394
- ### Core Loop Strategy
2395
- - Updated: Yes/No
2396
- - Confidence: High/Medium/Low
2397
- - Changes: [summary of changes]
2398
-
2399
- ### Onboarding
2400
- - Elements Found: X
2401
- - Gaps Identified: X
2402
- - Changes: [summary of changes]
2403
-
2404
- ### User Guide
2405
- - Features Documented: X
2406
- - Missing: X
2407
- - Changes: [summary of changes]
2408
-
2409
- ### Next Steps
2410
- - [ ] Review _OFFICE/CORE_LOOP.md
2411
- - [ ] Add missing onboarding elements
2412
- - [ ] Document new features
2413
- \`\`\`
2414
-
2415
- ## Interactive Question Flow
2416
-
2417
- The /office command uses a conversational approach:
2418
-
2419
- 1. **Introduction**: "Let's update your product office documents. I'll ask some questions about your product strategy and user experience."
2420
-
2421
- 2. **Strategy Questions** (if running strategy):
2422
- - "In one sentence, what do users primarily DO in your app?"
2423
- - "What's the biggest friction point or obstacle for users?"
2424
- - "What's the core reward or motivation that keeps users engaged?"
2425
-
2426
- 3. **Onboarding Questions** (if running onboarding):
2427
- - "Describe what a new user sees on their first visit"
2428
- - "What's the 'aha moment' you want to guide new users to?"
2429
- - "Do you have any guided tours, tooltips, or welcome modals?"
2430
-
2431
- 4. **Guide Questions** (if running guide):
2432
- - "What are the top 3-5 features users should know about?"
2433
- - "What questions do users commonly ask?"
2434
- - "Are there keyboard shortcuts or power-user features?"
2435
-
2436
- 5. **Confirmation**: Ask user to confirm updates before writing to files.
2437
- `;
2438
-
2439
- await fs.writeFile(
2440
- path.join(cwd, ".claude", "commands", "office.md"),
2441
- officeCommand,
2442
- );
2443
2861
  }
2444
2862
 
2445
2863
  async function createSettings(cwd, answers) {
2446
- if (answers.includeStorybook && answers.netlifyAuthToken) {
2447
- const localSettings = {
2448
- env: {
2449
- NETLIFY_AUTH_TOKEN: answers.netlifyAuthToken,
2450
- NETLIFY_STORYBOOK_SITE_ID: answers.netlifySiteId,
2451
- },
2452
- };
2453
-
2454
- await fs.writeFile(
2455
- path.join(cwd, ".claude", "settings.local.json"),
2456
- JSON.stringify(localSettings, null, 2),
2457
- );
2458
-
2459
- const gitignorePath = path.join(cwd, ".gitignore");
2460
- let gitignoreContent = "";
2461
- try {
2462
- gitignoreContent = await fs.readFile(gitignorePath, "utf-8");
2463
- } catch {
2464
- // .gitignore doesn't exist yet
2465
- }
2466
-
2467
- const entriesToAdd = [".claude/settings.local.json", "storybook-static/"];
2468
-
2469
- const linesToAdd = entriesToAdd.filter(
2470
- (entry) => !gitignoreContent.includes(entry),
2471
- );
2472
-
2473
- if (linesToAdd.length > 0) {
2474
- const newContent =
2475
- gitignoreContent.trim() +
2476
- (gitignoreContent.trim() ? "\n\n" : "") +
2477
- "# Farmwork - Storybook deployment\n" +
2478
- linesToAdd.join("\n") +
2479
- "\n";
2480
- await fs.writeFile(gitignorePath, newContent);
2481
- }
2482
- }
2864
+ // Settings function reserved for future use
2483
2865
  }
2484
2866
 
2485
2867
  async function createProduceConfig(cwd, answers) {
2486
2868
  const config = {
2487
- version: "1.2.0",
2869
+ version: "1.3.0",
2488
2870
  projectName: answers.projectName,
2489
2871
  commands: {
2490
2872
  test: answers.testCommand,
@@ -2492,21 +2874,11 @@ async function createProduceConfig(cwd, answers) {
2492
2874
  lint: answers.lintCommand,
2493
2875
  },
2494
2876
  features: {
2495
- storybook: answers.includeStorybook || false,
2496
2877
  i18n: answers.includeI18n || false,
2497
2878
  },
2498
- audits: ["FARMHOUSE", "SECURITY", "PERFORMANCE", "ACCESSIBILITY", "CODE_QUALITY", "TESTS", "GARDEN", "COMPOST", "RESEARCH"],
2879
+ audits: ["FARMHOUSE", "SECURITY", "PERFORMANCE", "ACCESSIBILITY", "CODE_QUALITY", "TESTS", "GARDEN", "COMPOST", "RESEARCH", "GREENFIELD", "BROWNFIELD"],
2499
2880
  };
2500
2881
 
2501
- if (answers.includeStorybook) {
2502
- config.storybook = {
2503
- url: answers.storybookUrl || null,
2504
- passwordProtected: answers.passwordProtect || false,
2505
- deployCommand:
2506
- "npx netlify deploy --dir=storybook-static --site=$NETLIFY_STORYBOOK_SITE_ID --prod",
2507
- };
2508
- }
2509
-
2510
2882
  await fs.writeFile(
2511
2883
  path.join(cwd, ".farmwork.json"),
2512
2884
  JSON.stringify(config, null, 2),