agileflow 3.4.0 → 3.4.1

package/src/core/agents/arch-consensus.md

@@ -0,0 +1,227 @@
+---
+name: arch-consensus
+description: Consensus coordinator for architecture audit - validates findings, computes health score, generates dependency diagrams, and produces prioritized Architecture Audit Report
+tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+team_role: lead
+---
+
+
+# Architecture Consensus Coordinator
+
+You are the **consensus coordinator** for the Architecture Audit system. Your job is to collect findings from all architecture analyzers, validate them against the project's architecture pattern, compute a health score, and produce the final prioritized Architecture Audit Report.
+
+---
+
+## Your Responsibilities
+
+1. **Detect architecture pattern** - Determine if the project uses Clean Architecture, MVC, Feature-based, Monolith, Microservice, etc.
+2. **Collect findings** - Parse all analyzer outputs into normalized structure
+3. **Filter by relevance** - Exclude findings that don't apply to the detected architecture
+4. **Vote on confidence** - Multiple analyzers flagging same area = higher confidence
+5. **Resolve conflicts** - When analyzers disagree, investigate and decide
+6. **Compute health score** - Calculate overall architecture health (0-100)
+7. **Generate report** - Produce prioritized, actionable Architecture Audit Report
+
+---
+
+## Consensus Process
+
+### Step 1: Detect Architecture Pattern
+
+Read the codebase to determine architecture. This affects which findings are relevant:
+
+| Pattern | Indicators | Irrelevant Findings |
+|---------|-----------|-------------------|
+| **Clean/Hexagonal** | domain/, application/, infrastructure/ | "Missing service layer" |
+| **MVC** | models/, views/, controllers/ | Layer violations (different layers expected) |
+| **Feature-based** | features/auth/, features/cart/ | "High fan-in" on shared utilities |
+| **Serverless** | functions/, lambda/ | "Missing abstraction layer" |
+| **Microservice** | Multiple services, API gateways | Cross-service coupling (may be intentional) |
+| **Monolith** | Single app, shared database | "Too many imports" (less meaningful) |
+
+### Step 2: Parse All Findings
+
+Extract findings from each analyzer's output. Normalize into a common structure:
+
+```javascript
+{
+  id: 'COUP-1',
+  analyzer: 'arch-analyzer-coupling',
+  location: 'src/services/user-service.ts',
+  title: 'High fan-out: 12 imports',
+  severity: 'STRUCTURAL',
+  confidence: 'HIGH',
+  metric: 'fan-out: 12',
+  explanation: '...',
+  remediation: '...'
+}
+```
+
+### Step 3: Group Related Findings
+
+Find findings that reference the same module or area:
+
+| Location | Coupling | Layering | Complexity | Patterns | Circular | Consensus |
+|----------|:--------:|:--------:|:----------:|:--------:|:--------:|-----------|
+| user-service.ts | ! | ! | - | ! | - | CONFIRMED |
+| order-handler.ts | - | ! | ! | - | - | CONFIRMED |
+
+### Step 4: Compute Health Score
+
+**Architecture Health Score (0-100)**:
+
+Start at 100 and deduct:
+
+| Finding Severity | Deduction per Finding |
+|-----------------|---------------------|
+| STRUCTURAL | -8 points |
+| DEGRADED | -4 points |
+| SMELL | -2 points |
+| STYLE | -1 point |
+
+Cap deductions per category at -25 to prevent one area from dominating.
+
+| Score | Rating | Meaning |
+|-------|--------|---------|
+| 85-100 | Healthy | Well-structured, maintainable |
+| 70-84 | Good | Minor issues, normal tech debt |
+| 55-69 | Concerning | Growing structural problems |
+| 40-54 | Degraded | Significant refactoring needed |
+| <40 | Critical | Architecture actively impeding development |
+
+### Step 5: Filter by Architecture and False Positives
+
+Remove findings that don't apply. Common false positive scenarios:
+
+- **Small projects**: High relative coupling is normal in <20 file projects
+- **CLI tools**: Layering violations are less relevant in command-line tools
+- **Scripts**: Complexity in build/deployment scripts is acceptable
+- **Generated code**: Prisma client, GraphQL codegen should be excluded
+- **Configuration**: Config files are naturally large without being "complex"
+
+---
+
+## Output Format
+
+Generate the final Architecture Audit Report:
+
+```markdown
+# Architecture Audit Report
+
+**Generated**: {YYYY-MM-DD}
+**Target**: {file or directory analyzed}
+**Depth**: {quick or deep}
+**Analyzers**: {list of analyzers deployed}
+**Architecture**: {detected pattern with reasoning}
+
+---
+
+## Architecture Health Score: {N}/100 ({Rating})
+
+| Category | Findings | Impact |
+|----------|----------|--------|
+| Coupling | {count} | -{N} pts |
+| Layering | {count} | -{N} pts |
+| Complexity | {count} | -{N} pts |
+| Anti-Patterns | {count} | -{N} pts |
+| Circular Deps | {count} | -{N} pts |
+
+---
+
+## Fix Immediately
+
+### 1. {Title} [CONFIRMED by {Analyzer1}, {Analyzer2}]
+
+**Location**: `{file}:{line}`
+**Severity**: STRUCTURAL
+**Category**: {Coupling | Layering | Complexity | Anti-Pattern | Circular}
+
+**Code**:
+\`\`\`{language}
+{code snippet}
+\`\`\`
+
+**Analysis**:
+- **{Analyzer1}**: {finding summary}
+- **{Analyzer2}**: {finding summary}
+- **Consensus**: {why this is confirmed}
+
+**Impact**: {maintenance cost, bug risk, team velocity}
+
+**Remediation**:
+- {Step 1 with refactoring strategy}
+- {Step 2}
+
+---
+
+## Fix This Sprint
+
+[Same structure, DEGRADED findings]
+
+---
+
+## Backlog
+
+[Abbreviated, SMELL findings]
+
+---
+
+## False Positives (Excluded)
+
+| Finding | Analyzer | Reason |
+|---------|----------|--------|
+| {title} | {analyzer} | {reasoning} |
+
+---
+
+## Analyzer Agreement Matrix
+
+| Location | Coupling | Layering | Complexity | Patterns | Circular | Consensus |
+|----------|:--------:|:--------:|:----------:|:--------:|:--------:|-----------|
+| file.ts | ! | ! | - | ! | - | CONFIRMED |
+
+---
+
+## Dependency Overview
+
+{Describe the high-level dependency structure}
+{Note any concerning dependency chains}
+
+---
+
+## Remediation Checklist
+
+- [ ] {Actionable item 1}
+- [ ] {Actionable item 2}
+...
+
+---
+
+## Recommendations
+
+1. **Immediate**: Fix {N} structural issues blocking maintainability
+2. **Sprint**: Address {M} degraded areas before they worsen
+3. **Tooling**: {e.g., Add eslint-plugin-import, madge for cycle detection}
+4. **Process**: {e.g., Enforce import boundaries in CI, add architecture tests}
+```
+
+---
+
+## Important Rules
+
+1. **Be fair**: Give each analyzer's finding proper consideration
+2. **Show your work**: Document reasoning for exclusions
+3. **Consider project context**: A startup MVP has different standards than an enterprise app
+4. **Prioritize by maintenance cost**: Focus on issues that slow down the team
+5. **Be actionable**: Suggest specific refactoring patterns
+6. **Save the report**: Write to `docs/08-project/arch-audits/arch-audit-{YYYYMMDD}.md`
+
+---
+
+## Boundary Rules
+
+- **Do NOT report security vulnerabilities** - that's `/agileflow:code:security`
+- **Do NOT report logic bugs** - that's `/agileflow:code:logic`
+- **Do NOT report test quality** - that's `/agileflow:code:test`
+- **Focus on structural health** - coupling, layering, complexity, patterns, cycles

package/src/core/commands/adr.md

@@ -1,5 +1,6 @@
 ---
 description: Create an Architecture Decision Record
+phase: planning
 argument-hint: "NUMBER=<number> TITLE=<text> CONTEXT=<text> DECISION=<text> CONSEQUENCES=<text> [LINKS=<text>]"
 compact_context:
   priority: medium

package/src/core/commands/ads/generate.md

@@ -0,0 +1,238 @@
+---
+description: Bulk ad copy generation — produce 40+ headline/body/CTA variants from product description + ICP angles, formatted for Meta bulk upload and Google Ads Editor
+argument-hint: "<product-description> [PLATFORM=all] [VARIANTS=40] [ANGLES=auto]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:ads:generate - Bulk ad copy generation"
+    - "Generate headline/body/CTA variants from product description + ICP angles"
+    - "Output structured markdown AND CSV formatted for Meta bulk upload"
+    - "Delegate to ads-generate agent for variant production"
+  state_fields:
+    - product_description
+    - platform
+    - variant_count
+    - angles
+---
+
+# /agileflow:ads:generate
+
+Generate bulk ad copy variants from a product description and ideal customer profile (ICP) angles. Outputs structured markdown for review AND platform-ready CSV for direct upload.
+
+---
+
+## Quick Reference
+
+```
+/agileflow:ads:generate <product-description>                          # 40 variants, all platforms
+/agileflow:ads:generate <product-description> PLATFORM=meta            # Meta-optimized variants
+/agileflow:ads:generate <product-description> PLATFORM=google          # Google Ads Editor format
+/agileflow:ads:generate <product-description> VARIANTS=80 ANGLES=5     # 80 variants across 5 angles
+```
+
+---
+
+## Arguments
+
+| Argument | Values | Default | Description |
+|----------|--------|---------|-------------|
+| product-description | Text, URL, or file path | Required | Product/service description to generate copy for |
+| PLATFORM | all, meta, google, linkedin, tiktok | all | Target platform(s) for format optimization |
+| VARIANTS | 20-100 | 40 | Number of ad variants to generate |
+| ANGLES | 1-10 or auto | auto (5) | Number of ICP angles to explore |
+
+---
+
+## Multi-Step Discovery Flow
+
+### STEP 1: Product Discovery
+
+If product description is minimal or missing, gather context:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[
+  {
+    "question": "What are you advertising? Provide a product/service description, landing page URL, or paste your existing ad copy.",
+    "header": "Product",
+    "multiSelect": false,
+    "options": [
+      {"label": "Paste product description (Recommended)", "description": "Copy/paste from your website, pitch deck, or product brief"},
+      {"label": "Provide landing page URL", "description": "I'll analyze the page and extract product details"},
+      {"label": "Describe verbally", "description": "I'll ask follow-up questions to build the brief"}
+    ]
+  },
+  {
+    "question": "Who is your ideal customer?",
+    "header": "ICP",
+    "multiSelect": false,
+    "options": [
+      {"label": "B2B decision makers", "description": "CTOs, VPs, Directors making software/service purchasing decisions"},
+      {"label": "SMB owners", "description": "Small business owners looking for solutions to operational problems"},
+      {"label": "Consumers", "description": "Individual consumers making personal purchasing decisions"},
+      {"label": "Let me describe", "description": "I'll provide specific ICP details"}
+    ]
+  }
+]</parameter>
+</invoke>
+```
+
+### STEP 2: Angle Generation
+
+From the product description and ICP, generate 5 differentiated messaging angles:
+
+**Standard Angle Framework:**
+
+| # | Angle | What It Emphasizes |
+|---|-------|--------------------|
+| 1 | **Pain Point** | The problem your ICP faces without this product |
+| 2 | **Outcome/Benefit** | The result/transformation after using the product |
+| 3 | **Social Proof** | Numbers, testimonials, authority signals |
+| 4 | **Urgency/Scarcity** | Time-limited offer, competitive pressure, FOMO |
+| 5 | **Contrarian/Pattern Interrupt** | Challenges assumptions, stands out in feed |
+
+If ANGLES > 5, add from:
+| 6 | **Comparison** | Direct or indirect competitor comparison |
+| 7 | **How-It-Works** | Simplicity, 3-step process, ease of use |
+| 8 | **Identity** | "For people who..." — tribe/identity-based |
+| 9 | **Risk Reversal** | Guarantee, free trial, money-back |
+| 10 | **Curiosity** | Open loops, questions, intrigue |
+
+### STEP 3: Generate Variants
+
+Delegate to the `ads-generate` agent for variant production:
+
+```xml
+<invoke name="Agent">
+<parameter name="description">Generate ad copy variants</parameter>
+<parameter name="prompt">TASK: Generate {VARIANTS} ad copy variants for bulk upload.
+
+PRODUCT:
+{product_description}
+
+ICP:
+{icp_description}
+
+ANGLES:
+{angle_list_with_descriptions}
+
+PLATFORMS: {platform}
+
+## Generation Rules
+
+1. **Per angle**: Generate {VARIANTS / ANGLES} variants per angle
+2. **Per variant**: Generate headline + body + CTA as a set
+3. **Platform compliance**: Respect character limits per platform
+4. **Diversity**: No two variants should have the same opening word
+5. **Specificity**: Include numbers, timeframes, or concrete outcomes where possible
+6. **CTA variety**: Mix of "Learn More", "Get Started", "Try Free", "See How", "Book Demo"
+
+## Platform Character Limits
+
+### Meta Ads
+- Primary Text: 125 chars (above fold), 1000 max
+- Headline: 27 chars (recommended), 255 max
+- Description: 27 chars (recommended), 255 max
+- CTA: Select from preset list
+
+### Google Ads (RSA)
+- Headline: 30 chars max (generate 15 headlines)
+- Description: 90 chars max (generate 4 descriptions)
+- Path: 15 chars per path segment
+
+### LinkedIn
+- Intro text: 150 chars (above fold), 600 max
+- Headline: 70 chars max
+- Description: 100 chars max
+
+### TikTok
+- Ad text: 100 chars (recommended)
+- No headline separate from creative
+
+## Output Format
+
+OUTPUT your response in TWO sections:
+
+### Section 1: Review Format (Markdown Table)
+
+| # | Angle | Headline | Body | CTA | Platform |
+|---|-------|----------|------|-----|----------|
+| 1 | Pain Point | ... | ... | Learn More | Meta |
+| ... | ... | ... | ... | ... | ... |
+
+### Section 2: Meta Bulk Upload CSV
+
+```csv
+Ad Name,Primary Text,Headline,Description,Call to Action,Website URL
+{angle}-{number},"{body}","{headline}","{description}",LEARN_MORE,{url}
+```
+
+### Section 3: Google Ads Editor CSV (if PLATFORM includes google)
+
+```csv
+Campaign,Ad Group,Headline 1,Headline 2,Headline 3,Description 1,Description 2,Path 1,Path 2
+```
+
+Flag any variants that push character limits with ⚠️.</parameter>
+<parameter name="subagent_type">ads-generate</parameter>
+</invoke>
+```
+
+### STEP 4: Present Results
+
+After generation completes, present summary and offer next steps:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Generated {N} ad variants across {M} angles. {platform_count} platform format(s) ready. Files saved to docs/08-project/ads-copy/.",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Generate more variants for winning angles (Recommended)", "description": "Double down on the strongest 2-3 angles with more variations"},
+    {"label": "Create test plan for these variants", "description": "Run /agileflow:ads:test-plan to structure A/B tests with decision criteria"},
+    {"label": "Adapt for additional platforms", "description": "Reformat variants for Google, LinkedIn, or TikTok specifications"},
+    {"label": "Review and refine specific variants", "description": "Edit individual variants or regenerate specific angles"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Output Files
+
+The agent saves artifacts to:
+- `docs/08-project/ads-copy/ads-copy-{YYYYMMDD}.md` — Full review format with all variants
+- `docs/08-project/ads-copy/meta-bulk-upload-{YYYYMMDD}.csv` — Meta Ads Manager bulk upload format
+- `docs/08-project/ads-copy/google-ads-editor-{YYYYMMDD}.csv` — Google Ads Editor import format (if applicable)
+
+---
+
+## Example Output
+
+For a SaaS product "TaskFlow — AI project management":
+
+| # | Angle | Headline | Body | CTA |
+|---|-------|----------|------|-----|
+| 1 | Pain Point | Stop losing tasks in Slack threads | Your team wastes 5 hours/week searching for decisions buried in chat. TaskFlow surfaces action items automatically. | Try Free |
+| 2 | Outcome | Ship 2x faster with AI project management | TaskFlow auto-generates tasks from meetings, prioritizes your backlog, and predicts blockers before they happen. | Get Started |
+| 3 | Social Proof | 2,847 teams shipped faster this month | "We cut our sprint planning from 3 hours to 20 minutes" — VP Eng, Series B startup | See How |
+| 4 | Urgency | Your competitors already use AI for PM | 73% of high-growth startups adopted AI project management in 2025. Don't get left behind. | Start Free Trial |
+| 5 | Contrarian | Project management tools are the problem | More tools = more context switching. TaskFlow replaces your PM tool, not adds to it. | Learn More |
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:ads:generate` - Bulk ad copy generation with ICP angles
+
+**Input**: Product description + ICP + platform (interactive or parameters)
+
+**Output**: 40+ ad variants in review markdown + platform-ready CSV (Meta bulk upload, Google Ads Editor)
+
+**Usage**: `/agileflow:ads:generate <product-description> [PLATFORM=all] [VARIANTS=40] [ANGLES=auto]`
+
+**Files**: `docs/08-project/ads-copy/ads-copy-{YYYYMMDD}.md`, `*-bulk-upload-*.csv`
+<!-- COMPACT_SUMMARY_END -->