ardfw 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ardfw",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Agentics Framework CLI - Multi-agent system for Claude Code and OpenCode",
   "bin": {
     "ardfw": "tools/ard-npx-wrapper.js",
@@ -8,7 +8,8 @@
   },
   "files": [
     "tools/",
-    "src/project_config/"
+    "src/project_config/",
+    "src/workflows/"
   ],
   "scripts": {
     "test": "echo \"No tests yet\"",

package/src/project_config/AGENTICS.md

@@ -1,19 +1,482 @@
-# Project: {{PROJECT_NAME}}
+# AGENTICS Framework Reference
 
-## Overview
-<!-- Describe your project here -->
+> Agent-facing documentation for the Agentics multi-agent framework.
 
-## Tech Stack
-<!-- List key technologies, frameworks, and tools -->
+This document consolidates prompt engineering guidelines, subagent specifications, and workflow patterns into a single reference for agents operating within the framework.
 
-## Project Structure
-<!-- Describe directory layout and organization -->
+---
 
-## Conventions
-<!-- Document coding conventions, naming patterns, etc. -->
+## Table of Contents
 
-## Development Commands
-<!-- Common dev commands for building, testing, running -->
+1. [Prompt Engineering Framework](#1-prompt-engineering-framework)
+2. [Subagent Reference](#2-subagent-reference)
+3. [Workflow Categories](#3-workflow-categories)
+4. [When to Use Parent vs Subagent Workflows](#4-when-to-use-parent-vs-subagent-workflows)
+5. [Invocation Patterns](#5-invocation-patterns)
 
-## Notes for AI Agents
-<!-- Special instructions, constraints, or context for AI assistance -->
+---
+
+## 1. Prompt Engineering Framework
+
+> Scale your compute to scale your impact. Each agentic prompt you write can be used, reused, and chained.
+
+### 1.1 Prompt Levels
+
+Prompts are structured at four levels of complexity:
+
+| Level | Name | Description | Difficulty |
+|-------|------|-------------|------------|
+| **L1** | Metadata | Frontmatter: description, tools, arguments, model | C Tier |
+| **L2** | Workflow | Sequential numbered steps | C Tier |
+| **L3** | Control Flow | Conditions and loops with `<loop>` XML blocks | B Tier |
+| **L4** | Delegation | Sub-agent invocation via Task tool | A Tier |
+
+### 1.2 Prompt Sections & Tier System
+
+Include sections based on prompt complexity:
+
+| Section | Description | Tier |
+|---------|-------------|------|
+| **Metadata** | Frontmatter with description, allowed-tools, argument-hints, model | C |
+| **Workflow** | Sequential activities to perform | C |
+| **Report** | Output format specification | C |
+| **Information** | System context and structure (precedes workflow) | B |
+| **Variables** | What the agent works with (inputs, paths, configs) | A |
+| **Context Map** | Files/resources to fetch before execution | A |
+| **Quality Checklist** | Validation criteria for output | S |
+
+**Tier Progression:**
+- **C Tier**: Metadata + Workflow + Report (simple commands)
+- **B Tier**: + Information (contextual commands)
+- **A Tier**: + Variables + Context Map (complex commands)
+- **S Tier**: + Quality Checklist (production-grade)
+
+### 1.3 Metadata Fields
+
+```yaml
+---
+name: command-name
+description: When to invoke and what it does
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+argument-hints: [arg1] [arg2]
+model: sonnet | opus | haiku
+---
+```
+
+### 1.4 Control Flow with XML Blocks
+
+For repeating operations, use XML loop blocks:
+
+```markdown
+## Workflow
+
+1. Initialize environment
+2. For each item, execute the processing loop:
+
+<process-loop>
+- Load item from queue
+- Transform data
+- Validate output
+- Save results
+</process-loop>
+
+3. Generate summary report
+```
+
+### 1.5 Step-File Architecture
+
+Workflows use micro-file design with strict execution rules:
+
+**Principles:**
+- **Micro-file design**: One step per file
+- **Just-in-time loading**: Only current step in memory
+- **Sequential enforcement**: No skipping or optimization
+- **State tracking**: Progress in frontmatter `stepsCompleted` array
+- **Append-only building**: Documents grow through steps
+
+**Execution Rules:**
+- NEVER load multiple step files simultaneously
+- ALWAYS read entire step file before execution
+- NEVER skip steps or optimize sequence
+- ALWAYS update frontmatter when completing steps
+- For parent workflows: HALT at menus for user input
+- For subagent workflows: AUTO-PROCEED through all steps
+
+---
+
+## 2. Subagent Reference
+
+> Subagents execute delegated tasks without parent context. They are prompted by the parent agent, not the user.
+
+### 2.1 Context Engineering Principles
+
+- **Reduce Context**: Less context = better focus = predictable responses
+- **Delegate**: Offload work without polluting parent context window
+- **Isolate**: Subagents have no awareness of each other
+
+### 2.2 Agent Registry
+
+| Agent | Role | Model | Tools | Access |
+|-------|------|-------|-------|--------|
+| **architect** | System design, tech stack decisions | opus | Read, Glob, Grep, WebFetch, WebSearch | read-only |
+| **analyst** | Business analysis, requirements, metrics | sonnet | Read, Glob, Grep, WebFetch, WebSearch | read-only |
+| **dev** | Implementation, debugging, testing | sonnet | Read, Write, Edit, Bash, Grep, Glob | write |
+| **pm** | Product management, PRDs, priorities | opus | Read, Glob, Grep, WebFetch, WebSearch | read-only |
+| **ux-designer** | UI/UX design, accessibility | sonnet | Read, Glob, Grep, WebFetch | read-only |
+| **tech-writer** | Documentation, guides, API docs | sonnet | Read, Glob, Grep, WebFetch | read-only |
+| **data-science** | Analytics, ML, A/B testing | sonnet | Read, Glob, Grep, WebFetch, WebSearch | read-only |
+| **sm** | Process coordination, blockers | sonnet | Read, Glob, Grep | read-only |
+| **agent-dev** | Agent specifications, workflows | opus | Read, Write, Edit, Glob, Grep, Bash | write |
+| **meta-agent** | Ecosystem management, audits | opus | Read, Write, Edit, Glob, Grep, Bash | write |
+
+### 2.3 When to Invoke Each Agent
+
+| Agent | Delegate When | Use Proactively |
+|-------|---------------|-----------------|
+| **architect** | PRD needs technical translation, tech stack decisions | Designing new systems, reviewing architectures |
+| **analyst** | Business questions need data-driven answers | Requirements elicitation, impact assessment |
+| **dev** | Implementing features from specs, fixing bugs | After bug reports, code review requests |
+| **pm** | Translating user needs into PRDs | New feature requests, prioritization needed |
+| **ux-designer** | Designing interfaces, accessibility audits | Frontend UX quality review |
+| **tech-writer** | APIs need documentation | After dev completes implementation |
+| **data-science** | Metrics definition, A/B test design | Compute optimization, statistical validation |
+| **sm** | Multi-agent coordination needed, blockers arise | Process improvement, workflow optimization |
+| **agent-dev** | Creating new agents, updating definitions | Agent capability assessment |
+| **meta-agent** | Ecosystem audit, orchestration design | Agent consistency checks |
+
+### 2.4 Isolation Protocol
+
+All subagents follow strict isolation rules:
+
+1. **Cannot communicate** directly with other sub-agents
+2. **Cannot spawn** or invoke other sub-agents
+3. **All outputs** return exclusively to the parent agent
+4. **No cross-agent awareness** - each operates independently
+5. **Sequential chaining** managed only by parent agent
+
+### 2.5 Agent Definition Structure
+
+Agent files in `src/system_config/agents/*.md` follow this structure:
+
+```markdown
+---
+name: agent-name
+description: Trigger condition and purpose
+tools: Read, Glob, Grep
+model: sonnet
+---
+
+# Agent Name
+
+## Use Cases
+- Delegate when...
+- Use proactively when...
+
+## Objectives
+- Primary goals
+
+## Constraints
+- Boundaries and limitations
+
+## Communication Protocol
+[Standard isolation rules]
+
+## Report Format
+[Output structure]
+```
+
+---
+
+## 3. Workflow Organization
+
+### 3.1 Workflow Modules
+
+**Workflow Modules** are top-level organizational folders that group related workflows together. Each module:
+- Contains one or more related workflows
+- Has a dedicated artifact output folder in `_ard/artifacts/{module-name}/`
+- Is registered in `src/workflows/parent/parent.yaml`
+
+**Parent Workflow Modules:**
+
+| Module | Description | Workflows | Artifact Path |
+|--------|-------------|-----------|---------------|
+| `analysis` | Discovery and research | create-product-brief, research | `{artifacts.analysis}` |
+| `plan-workflows` | Requirements and UX | prd, create-ux-design | `{artifacts.plan-workflows}` |
+| `architecture` | System design | create-architecture, create-epics-and-stories, check-implementation-readiness | `{artifacts.architecture}` |
+| `quick-flow` | Rapid development | create-tech-spec, quick-dev | `{artifacts.quick-flow}` |
+| `core` | Support workflows | party-mode, brainstorming | - |
+
+**Standalone Workflows** (no module):
+- `create-workflow`, `edit-workflow`, `create-module` - Meta/framework extension
+- `document-project`, `generate-project-context` - Utility
+
+### 3.2 Creating New Workflows & Modules
+
+When creating new workflows or modules:
+
+1. **New Workflow in Existing Module:**
+   - Add workflow folder to `src/workflows/parent/{module-name}/{workflow-name}/`
+   - Register in `parent.yaml` under the module's `workflows:` section
+
+2. **New Module:**
+   - Create folder `src/workflows/parent/{module-name}/`
+   - Add module definition to `parent.yaml`
+   - Add artifact path to `config.js`: `artifacts.{module-name}`
+
+Use `/create-workflow` to create a new workflow, or `/create-module` to create a new module.
+
+### 3.3 Parent Workflows (Interactive)
+
+Parent workflows require **user collaboration** at decision points. They use menu gates where users select options to proceed.
+
+*Full inventory: `src/workflows/parent/parent.yaml`*
+
+### 3.4 Subagent Workflows (Non-interactive)
+
+Subagent workflows execute **autonomously** without user gates. They have defined input/output contracts.
+
+| Agent | Example Workflows | Complexity | Total |
+|-------|-------------------|------------|-------|
+| **architect** | design-component, review-architecture, select-technology, create-adr, define-api-contracts | 1 multi-step, 4 simple | 5 |
+| **analyst** | analyze-requirements, competitive-analysis, define-metrics, impact-assessment, gap-analysis | 2 multi-step, 3 simple | 5 |
+| **dev** | implement-feature, fix-bug, code-review, write-tests, refactor-code | 1 multi-step, 4 simple | 5 |
+| **pm** | write-user-story, prioritize-features, scope-feature, define-acceptance-criteria, release-planning | 1 multi-step, 4 simple | 5 |
+| **ux-designer** | design-component, accessibility-audit, user-flow-analysis, design-review, create-wireframes | 1 multi-step, 4 simple | 5 |
+| **tech-writer** | document-api, write-readme, create-guide, document-feature, write-release-notes | 1 multi-step, 4 simple | 5 |
+| **data-science** | design-metrics, design-ab-test, model-selection, data-quality-assessment, statistical-analysis | 2 multi-step, 3 simple | 5 |
+| **sm** | identify-blockers, facilitate-retrospective, process-improvement, sprint-planning-support, team-health-check | 1 multi-step, 4 simple | 5 |
+| **agent-dev** | create-agent-spec, design-agent-workflow, update-agent-definition, agent-capability-assessment, create-custom-skill | 2 multi-step, 3 simple | 5 |
+| **meta-agent** | agent-ecosystem-audit, design-agent-orchestration, agent-consistency-check, create-agent-cluster, agent-deprecation-plan | 2 multi-step, 3 simple | 5 |
+
+**Totals:** 10 agents, 50 workflows (15 multi-step, 35 simple)
+
+*Full inventory: `src/workflows/subagent/subagent.yaml`*
+
+---
+
+## 4. When to Use Parent vs Subagent Workflows
+
+### 4.1 Use Parent Workflows When:
+
+- **User collaboration required** at decision points
+- **Discovery-driven work** - exploring product vision, requirements, architecture
+- **Sequential human decisions** needed throughout the process
+- **Multi-step facilitation** requiring guidance at each stage
+- **Building planning artifacts** through dialogue (PRDs, specs, architecture docs)
+- **Strategic planning** with multiple options to evaluate
+
+**Key Indicator:** If the task requires "what do you think?" or "which option?" questions, use a parent workflow.
+
+### 4.2 Use Subagent Workflows When:
+
+- **Task can execute autonomously** without user gates
+- **Clear input contract** leads to **predictable output**
+- **Specialist expertise** needed (data science analysis, UX audit, code review)
+- **Re-usable building block** within larger parent workflows
+- **Delegated work** that doesn't need human review per step
+- **Context isolation** is beneficial (reduce parent context pollution)
+
+**Key Indicator:** If you can fully specify the task upfront with clear inputs and expected outputs, use a subagent workflow.
+
+### 4.3 Decision Matrix
+
+| Scenario | Use |
+|----------|-----|
+| "Help me figure out the product requirements" | Parent: prd |
+| "Analyze these requirements and document gaps" | Subagent: analyst/analyze-requirements |
+| "Design the system architecture" | Parent: create-architecture |
+| "Review this architecture for issues" | Subagent: architect/review-architecture |
+| "Implement user authentication" | Subagent: dev/implement-feature |
+| "Create a tech spec for this feature" | Parent: create-tech-spec |
+| "Write tests for this module" | Subagent: dev/write-tests |
+| "Help me prioritize the backlog" | Parent (if discussion needed) OR Subagent: pm/prioritize-features |
+
+---
+
+## 5. Invocation Patterns
+
+### 5.1 Task Tool - Subagent Delegation
+
+Use the Task tool to delegate work to a subagent:
+
+```markdown
+Use Task tool:
+  subagent_type: dev
+  prompt: |
+    Execute workflow: implement-feature
+
+    Input:
+      specification: |
+        Add user authentication with JWT tokens.
+        - Login endpoint POST /auth/login
+        - Register endpoint POST /auth/register
+        - Protected routes require Bearer token
+      target_files:
+        - src/routes/auth.ts
+        - src/middleware/auth.ts
+```
+
+### 5.2 Parent Workflow Loading
+
+To execute a parent workflow:
+
+```markdown
+Load workflow: src/workflows/parent/bmad-quick-flow/create-tech-spec/workflow.md
+
+Execute following step-file rules:
+1. Read entire step file before taking action
+2. Execute step instructions in order
+3. HALT at menu options and wait for user selection
+4. Update stepsCompleted array in frontmatter on completion
+5. Load next step file only after current step completes
+```
+
+### 5.3 Subagent Workflow from Parent
+
+When a parent workflow delegates to a subagent with a specific workflow:
+
+```markdown
+<delegate>
+Use Task tool:
+  subagent_type: analyst
+  prompt: |
+    Execute workflow: analyze-requirements
+
+    Input:
+      project_context: "E-commerce platform redesign for mobile-first experience"
+      stakeholders:
+        - product team
+        - engineering leads
+        - design team
+      existing_docs:
+        - docs/current-requirements.md
+        - docs/user-research.md
+</delegate>
+```
+
+### 5.4 Parallel Subagent Execution
+
+For independent tasks, invoke multiple subagents in parallel:
+
+```markdown
+<delegate-parallel>
+1. Use Task tool:
+   subagent_type: architect
+   prompt: Execute workflow: review-architecture
+   Input: { architecture_docs: ["docs/system-design.md"] }
+
+2. Use Task tool:
+   subagent_type: analyst
+   prompt: Execute workflow: impact-assessment
+   Input: { change_description: "Migrating to microservices" }
+
+3. Use Task tool:
+   subagent_type: data-science
+   prompt: Execute workflow: design-metrics
+   Input: { business_objective: "Improve checkout conversion" }
+</delegate-parallel>
+```
+
+---
+
+## Quick Reference
+
+### Prompt Tier Quick Selection
+
+| Complexity | Tier | Include |
+|------------|------|---------|
+| Simple command | C | Metadata, Workflow, Report |
+| Context-aware | B | + Information |
+| Complex with inputs | A | + Variables, Context Map |
+| Production-grade | S | + Quality Checklist |
+
+### Agent Quick Selection
+
+| Need | Agent |
+|------|-------|
+| Design systems | architect |
+| Analyze data/requirements | analyst |
+| Write code | dev |
+| Define product | pm |
+| Design UI | ux-designer |
+| Write docs | tech-writer |
+| Design experiments | data-science |
+| Coordinate work | sm |
+| Create agents | agent-dev |
+| Manage ecosystem | meta-agent |
+
+### Workflow Quick Selection
+
+| Interactive? | User decisions? | Use |
+|--------------|-----------------|-----|
+| Yes | Multiple | Parent workflow |
+| No | Upfront only | Subagent workflow |
+
+---
+
+## Configuration
+
+Framework configuration: `_ard/config.yaml`
+
+```yaml
+# Artifact output paths by module
+artifacts:
+  base: _ard/artifacts
+  # Parent workflow modules
+  analysis: _ard/artifacts/analysis
+  plan-workflows: _ard/artifacts/plan-workflows
+  architecture: _ard/artifacts/architecture
+  quick-flow: _ard/artifacts/quick-flow
+  # Subagent categories
+  analyst: _ard/artifacts/analyst
+  architect: _ard/artifacts/architect
+  # ... (one per agent type)
+
+# Workflow locations (system vs project separation)
+workflows:
+  system:
+    parent: _ard/workflows/system/parent
+    subagent: _ard/workflows/system/subagent
+  project:
+    parent: _ard/workflows/project/parent
+    subagent: _ard/workflows/project/subagent
+```
+
+### Workflow Directory Structure
+
+```
+_ard/workflows/
+  system/                    # Framework-provided workflows
+    parent/                  # Interactive parent workflows
+      parent.yaml            # Registry of parent workflows
+      analysis/              # Category folder
+        create-product-brief.md
+        research.md
+      quick-flow/
+        quick-dev.md
+        create-tech-spec.md
+      create-module.md       # Single workflows at root
+      create-workflow.md
+    subagent/                # Autonomous subagent workflows
+      subagent.yaml          # Registry of subagent workflows
+      dev/                   # Agent folder
+        implement-feature.md
+        fix-bug.md
+      analyst/
+        analyze-requirements.md
+  project/                   # User-customizable workflows
+    parent/                  # Custom parent workflows
+      .gitkeep
+    subagent/                # Custom subagent workflows
+      .gitkeep
+```
+
+**IDE Access:**
+- `.claude/commands/workflows/system/parent/` - System parent workflows
+- `.claude/commands/workflows/system/subagent/` - System subagent workflows
+- `.claude/commands/workflows/project/parent/` - Custom parent workflows
+- `.claude/commands/workflows/project/subagent/` - Custom subagent workflows
+
+---
+
+*Last updated: 2026-01-02*