rrce-workflow 0.1.0

package/docs/architecture.md

@@ -0,0 +1,346 @@
+# RRCE-Workflow Architecture
+
+> RR Context Engineering Workflow - A selection-agnostic agentic workflow system
+
+## Overview
+
+RRCE-Workflow is a TUI-based agentic code workflow generator designed to work seamlessly across:
+- **GitHub Copilot CLI**
+- **Antigravity IDE** (Google's agentic coding environment)
+- **VS Code** (with Copilot and other AI extensions)
+
+The system provides a structured multi-agent pipeline for software development tasks, with persistent knowledge caching and workspace-aware context management.
+
+## Core Principles
+
+1. **Selection Agnostic** - Identical prompts and behavior across all supported tools
+2. **Workspace Aware** - Respects project boundaries and maintainer preferences
+3. **Global Cache, Project Scoped** - Knowledge persists globally but is organized per-project
+4. **Non-Intrusive** - Minimal footprint in workspace; state lives in user home directory
+
+---
+
+## Directory Structure
+
+### Global Installation (`~/.rrce-workflow/`)
+
+```
+~/.rrce-workflow/
+├── config.yaml                              # User global configuration
+├── templates/                               # Default template store
+│   ├── meta.template.json                   # Task metadata template
+│   ├── research_output.md                   # Research brief template
+│   ├── planning_output.md                   # Execution plan template
+│   ├── executor_output.md                   # Implementation log template
+│   ├── documentation_output.md              # Handover note template
+│   └── docs/                                # Doc-type specific templates
+│       └── <doc-type>.md
+└── workspaces/                              # Project-scoped cache
+    └── <workspace-hash>/                    # SHA256 of workspace path
+        ├── workspace.json                   # Workspace metadata
+        ├── knowledge/                       # Project domain knowledge
+        │   └── <domain>.md
+        └── tasks/                           # Task state and artifacts
+            └── <task-slug>/
+                ├── meta.json                # Task metadata and status
+                ├── research/                # Research artifacts
+                ├── planning/                # Planning artifacts
+                ├── execution/               # Execution logs
+                └── docs/                    # Generated documentation
+```
+
+### Workspace Configuration (Optional)
+
+```
+<workspace>/
+└── .rrce-workflow.yaml                      # Project-specific config
+```
+
+---
+
+## Path Resolution
+
+### Storage Modes
+
+| Mode | Location | Use Case |
+|------|----------|----------|
+| `global` (default) | `~/.rrce-workflow/workspaces/<workspace-name>/` | Non-intrusive, survives repo deletion |
+| `workspace` | `<workspace>/.rrce-workflow/` | Portable, team-shareable |
+| `both` | Both locations with sync | Redundancy, flexibility |
+
+Configure via `.rrce-workflow.yaml`:
+```yaml
+storage:
+  mode: global  # or: workspace, both
+```
+
+### Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `RRCE_HOME` | Global installation path | `~/.rrce-workflow` |
+| `RRCE_WORKSPACE` | Explicit workspace root | Auto-detected |
+| `RRCE_AUTHOR` | Default author name | From `config.yaml` |
+
+### Template Variables
+
+| Variable | Resolves To |
+|----------|-------------|
+| `{{RRCE_HOME}}` | Global installation path |
+| `{{RRCE_DATA}}` | Data path (based on storage mode) |
+| `{{WORKSPACE_ROOT}}` | Workspace directory |
+| `{{WORKSPACE_NAME}}` | Project name (from config or directory) |
+
+### Workspace Detection Algorithm
+
+```
+1. If $RRCE_WORKSPACE is set → use it
+2. Walk up from CWD, find first directory containing:
+   - .git/
+   - .rrce-workflow.yaml
+3. Fall back to CWD
+```
+
+### Cross-Project References
+
+Reference another project's context when needed:
+```
+{{RRCE_HOME}}/workspaces/<other-project-name>/knowledge/project-context.md
+```
+
+**Use cases:**
+- FE project referencing BE API specs
+- Microservice referencing shared library conventions
+- Monorepo packages accessing root-level decisions
+
+---
+
+## Agent Pipeline
+
+```
+                                    ┌─────────────────┐
+                                    │      Init       │ ← First run or re-sync
+                                    │ (Project Setup) │
+                                    └────────┬────────┘
+                                             │
+                                             ▼
+                                  project-context.md
+                                             │
+        ┌────────────────────────────────────┴────────────────────────────────────┐
+        ▼                                                                          │
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│    Research     │────▶│    Planning     │────▶│    Executor     │────▶│  Documentation  │
+│   & Discussion  │     │  Orchestrator   │     │                 │     │                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘     └─────────────────┘
+        │                       │                       │                       │
+        ▼                       ▼                       ▼                       ▼
+   research.md              plan.md              execution.md          handover.md
+        │                       │                       │                       │
+        └───────────────────────┴───────────────────────┴───────────────────────┘
+                                        │
+                                        ▼
+                            {{RRCE_CACHE}}/knowledge/
+                              (Persistent Context)
+```
+
+### Agent Responsibilities
+
+| Agent | Role | Input | Output |
+|-------|------|-------|--------|
+| **Init** | Analyze codebase, establish project context | Workspace files | `project-context.md` |
+| **Research & Discussion** | Clarify requirements, surface risks | User request + context | Requirements brief |
+| **Planning Orchestrator** | Create actionable execution plan | Research brief | Prioritized task breakdown |
+| **Executor** | Implement and verify | Plan + skill scope | Code + execution log |
+| **Documentation** | Synthesize and handover | All artifacts | Release-ready docs |
+| **Sync** | Reconcile knowledge | Codebase state | Updated knowledge files |
+
+---
+
+## Configuration
+
+### Global Config (`~/.rrce-workflow/config.yaml`)
+
+```yaml
+version: 1
+
+# User identity
+author: "your-name"
+email: "your@email.com"
+
+# Default behaviors
+defaults:
+  auto_create_workspace_cache: true
+  sync_after_execution: false
+  
+# Editor integration hints (informational)
+editor:
+  preferred: "vscode"  # vscode | antigravity | vim | etc.
+```
+
+### Project Config (`<workspace>/.rrce-workflow.yaml`)
+
+```yaml
+version: 1
+
+# Cache control - repo maintainer can disable/customize
+cache:
+  enabled: true              # Set to false to disable global caching
+  knowledge: true            # Cache knowledge globally
+  tasks: true                # Cache task state globally
+
+# Template overrides
+templates:
+  dir: ./my-templates        # Local template directory (optional)
+
+# Project metadata
+project:
+  name: "my-project"         # Friendly name
+  
+# Author override
+author: "maintainer-name"    # Overrides global config for this project
+```
+
+---
+
+## Prompt Frontmatter Schema
+
+All agent prompts use YAML frontmatter for metadata and tool compatibility:
+
+```yaml
+---
+description: Brief description of the agent's purpose
+argument-hint: CLI-style argument hint for display
+agent: agent | ask | edit              # Copilot mode
+tools: ['search/codebase', ...]        # Available Copilot tools
+required-args:
+  - name: ARG_NAME
+    prompt: "Interactive prompt if arg is missing"
+optional-args:
+  - name: ARG_NAME
+    default: "default value"
+auto-identity:
+  user: "$GIT_USER"      # Auto-detect from `git config user.name`
+  model: "$AGENT_MODEL"  # Auto-detect from runtime (gemini-2.0, claude-sonnet, etc.)
+---
+```
+
+### Auto-Identity
+
+Identity is automatically detected - no user input required:
+
+| Variable | Source | Example |
+|----------|--------|---------|
+| `$GIT_USER` | `git config user.name` | "John Doe" |
+| `$AGENT_MODEL` | Runtime environment | "gemini-2.0-flash", "claude-sonnet-4" |
+
+---
+
+## Multi-Tool Integration
+
+RRCE-Workflow prompts are designed to work across multiple AI coding tools:
+
+### Tool Support Matrix
+
+| Tool | Prompt Location | Extension | Notes |
+|------|----------------|-----------|-------|
+| **Antigravity IDE** | `.agent/workflows/` | `.md` | Native workflow support |
+| **GitHub Copilot (VSCode)** | `.github/agents/` | `.agent.md` | Custom agents format |
+| **Copilot CLI** | Any location | `.md` | Reference via file path |
+
+### Wizard Command
+
+The TUI provides an interactive wizard to set up prompts for your preferred tools:
+
+```
+$ rrce-workflow wizard
+
+┌─────────────────────────────────────────────────────────┐
+│  RRCE-Workflow Project Setup                            │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Which AI tools do you use?                             │
+│                                                         │
+│  [x] GitHub Copilot (VSCode)                            │
+│  [x] Antigravity IDE                                    │
+│  [ ] Copilot CLI only                                   │
+│                                                         │
+│  ─────────────────────────────────────────────────────  │
+│                                                         │
+│  ✓ Created .github/prompts/*.prompt.md                  │
+│  ✓ Created .agent/workflows/*.md                        │
+│  ✓ Initialized project context                          │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Generated Files
+
+When you run `rrce-workflow wizard`, it creates:
+
+**For GitHub Copilot (VSCode):**
+```
+.github/prompts/
+├── init.prompt.md
+├── research.prompt.md
+├── planning.prompt.md
+├── executor.prompt.md
+├── documentation.prompt.md
+└── sync.prompt.md
+```
+
+**For Antigravity IDE:**
+```
+.agent/workflows/
+├── init.md
+├── research.md
+├── planning.md
+├── executor.md
+├── documentation.md
+└── sync.md
+```
+
+### Copilot-Specific Features
+
+Our prompts include Copilot-compatible frontmatter:
+
+| Field | Purpose | Values |
+|-------|---------|--------|
+| `agent` | Execution mode | `agent` (full), `ask` (read-only), `edit` (code changes) |
+| `tools` | Available tools | `search/codebase`, `search/web`, `terminalLastCommand`, etc. |
+
+---
+
+## Installation Flow (TUI First Run)
+
+```
+$ npx rrce-workflow
+
+┌─────────────────────────────────────────────────────────┐
+│  RRCE-Workflow Setup Wizard                             │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Welcome! Let's configure your workflow environment.    │
+│                                                         │
+│  Your name: [_________________]                         │
+│  Email (optional): [_________________]                  │
+│                                                         │
+│  ─────────────────────────────────────────────────────  │
+│                                                         │
+│  ✓ Created ~/.rrce-workflow/config.yaml                │
+│  ✓ Installed default templates                          │
+│  ✓ Ready to use!                                        │
+│                                                         │
+│  Run `rrce-workflow help` for available commands.       │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Future Considerations
+
+- [ ] Web UI for knowledge browsing
+- [ ] Cross-project knowledge sharing (opt-in)
+- [ ] Plugin system for custom agents
+- [ ] LLM-agnostic (support OpenAI, Anthropic, Gemini, local models)
+

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "rrce-workflow",
+  "version": "0.1.0",
+  "description": "RRCE-Workflow TUI - Agentic code workflow generator for AI-assisted development",
+  "author": "RRCE Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rryando/rrce-workflow.git"
+  },
+  "homepage": "https://github.com/rryando/rrce-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/rryando/rrce-workflow/issues"
+  },
+  "keywords": [
+    "ai",
+    "workflow",
+    "copilot",
+    "agent",
+    "tui",
+    "cli",
+    "code-generation",
+    "agentic",
+    "ink"
+  ],
+  "type": "module",
+  "module": "src/index.tsx",
+  "bin": {
+    "rrce-workflow": "bin/rrce-workflow.js"
+  },
+  "files": [
+    "src",
+    "agent-core",
+    "docs",
+    "bin"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.tsx",
+    "wizard": "bun run src/index.tsx wizard",
+    "start": "bun run src/index.tsx"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "ink": "^6.6.0",
+    "ink-select-input": "^6.2.0",
+    "react": "^18",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^18"
+  }
+}

package/src/App.tsx

@@ -0,0 +1,110 @@
+import * as React from 'react';
+import { Box, Text } from 'ink';
+import { Wizard, type WizardConfig } from './components/Wizard';
+import { AgentSelector } from './components/AgentSelector';
+import { loadPromptsFromDir, getAgentCorePromptsDir } from './lib/prompts';
+import { ensureDir, getAgentPromptPath, resolveDataPath, getRRCEHome } from './lib/paths';
+import type { ParsedPrompt } from './types/prompt';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AppMode = 'wizard' | 'select' | 'done';
+
+interface AppProps {
+  command?: string;
+}
+
+export function App({ command }: AppProps) {
+  const [mode, setMode] = React.useState<AppMode>(command === 'wizard' ? 'wizard' : 'select');
+  const [selectedPrompt, setSelectedPrompt] = React.useState<ParsedPrompt | null>(null);
+  const [message, setMessage] = React.useState<string | null>(null);
+
+  // Load prompts from agent-core
+  const prompts = loadPromptsFromDir(getAgentCorePromptsDir());
+
+  const handleWizardComplete = (config: WizardConfig) => {
+    // Create config file
+    const dataPath = resolveDataPath(config.storageMode, config.workspaceName, config.workspacePath);
+    ensureDir(dataPath);
+
+    // Copy prompts to appropriate locations
+    if (config.tools.copilot) {
+      const copilotPath = getAgentPromptPath(config.workspacePath, 'copilot');
+      ensureDir(copilotPath);
+      copyPromptsToDir(prompts, copilotPath, '.agent.md');
+    }
+
+    if (config.tools.antigravity) {
+      const antigravityPath = getAgentPromptPath(config.workspacePath, 'antigravity');
+      ensureDir(antigravityPath);
+      copyPromptsToDir(prompts, antigravityPath, '.md');
+    }
+
+    // Create workspace config
+    const workspaceConfigPath = path.join(config.workspacePath, '.rrce-workflow.yaml');
+    const configContent = `# RRCE-Workflow Configuration
+version: 1
+
+storage:
+  mode: ${config.storageMode}
+
+project:
+  name: "${config.workspaceName}"
+`;
+    fs.writeFileSync(workspaceConfigPath, configContent);
+
+    setMessage(`✓ Setup complete! Created config and copied agents.`);
+    setMode('done');
+  };
+
+  const handleAgentSelect = (prompt: ParsedPrompt) => {
+    setSelectedPrompt(prompt);
+    setMessage(`Selected: ${prompt.frontmatter.name}\n\nUse this agent in your IDE by invoking @${prompt.frontmatter.name}`);
+    setMode('done');
+  };
+
+  if (mode === 'wizard') {
+    return <Wizard onComplete={handleWizardComplete} />;
+  }
+
+  if (mode === 'done') {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Box borderStyle="round" borderColor="green" paddingX={2}>
+          <Text bold color="green">RRCE-Workflow</Text>
+        </Box>
+        <Box marginTop={1}>
+          <Text>{message}</Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  if (prompts.length === 0) {
+    return (
+      <Box flexDirection="column" padding={1}>
+        <Text color="yellow">No prompts found. Run `rrce-workflow wizard` to set up.</Text>
+      </Box>
+    );
+  }
+
+  return (
+    <AgentSelector
+      prompts={prompts}
+      workspaceName={path.basename(process.cwd())}
+      onSelect={handleAgentSelect}
+    />
+  );
+}
+
+function copyPromptsToDir(prompts: ParsedPrompt[], targetDir: string, extension: string) {
+  for (const prompt of prompts) {
+    const baseName = path.basename(prompt.filePath, '.md');
+    const targetName = baseName + extension;
+    const targetPath = path.join(targetDir, targetName);
+    
+    // Read the full content including frontmatter
+    const content = fs.readFileSync(prompt.filePath, 'utf-8');
+    fs.writeFileSync(targetPath, content);
+  }
+}

package/src/components/AgentSelector.tsx

@@ -0,0 +1,43 @@
+import * as React from 'react';
+import { Box, Text } from 'ink';
+import SelectInput from 'ink-select-input';
+import type { ParsedPrompt } from '../types/prompt';
+
+interface AgentSelectorProps {
+  prompts: ParsedPrompt[];
+  workspaceName: string;
+  onSelect: (prompt: ParsedPrompt) => void;
+}
+
+export function AgentSelector({ prompts, workspaceName, onSelect }: AgentSelectorProps) {
+  const items = prompts.map((p, i) => ({
+    key: p.filePath,
+    label: `${p.frontmatter.name} - ${p.frontmatter.description}`,
+    value: p,
+  }));
+
+  const handleSelect = (item: { value: ParsedPrompt }) => {
+    onSelect(item.value);
+  };
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Box borderStyle="round" borderColor="cyan" paddingX={2}>
+        <Text bold color="cyan">RRCE-Workflow</Text>
+        <Text> </Text>
+        <Text dimColor>| {workspaceName}</Text>
+      </Box>
+
+      <Box marginTop={1} flexDirection="column">
+        <Text>Select an agent:</Text>
+        <Box marginTop={1}>
+          <SelectInput items={items} onSelect={handleSelect} />
+        </Box>
+      </Box>
+
+      <Box marginTop={1}>
+        <Text dimColor>↑↓ to navigate, Enter to select</Text>
+      </Box>
+    </Box>
+  );
+}

package/src/components/Wizard.tsx

@@ -0,0 +1,135 @@
+import * as React from 'react';
+import { Box, Text, useInput } from 'ink';
+import SelectInput from 'ink-select-input';
+import type { StorageMode } from '../types/prompt';
+import { getGitUser } from '../lib/git';
+import { detectWorkspaceRoot, getWorkspaceName } from '../lib/paths';
+
+interface WizardProps {
+  onComplete: (config: WizardConfig) => void;
+}
+
+export interface WizardConfig {
+  workspaceName: string;
+  workspacePath: string;
+  storageMode: StorageMode;
+  tools: {
+    copilot: boolean;
+    antigravity: boolean;
+  };
+  gitUser: string | null;
+}
+
+type WizardStep = 'welcome' | 'storage' | 'tools' | 'confirm';
+
+const storageModeItems = [
+  { label: 'Global (~/.rrce-workflow/)', value: 'global' as StorageMode },
+  { label: 'Workspace (.rrce-workflow/)', value: 'workspace' as StorageMode },
+  { label: 'Both', value: 'both' as StorageMode },
+];
+
+export function Wizard({ onComplete }: WizardProps) {
+  const workspacePath = detectWorkspaceRoot();
+  const workspaceName = getWorkspaceName(workspacePath);
+  const gitUser = getGitUser();
+
+  const [step, setStep] = React.useState<WizardStep>('welcome');
+  const [storageMode, setStorageMode] = React.useState<StorageMode>('global');
+  const [tools, setTools] = React.useState({ copilot: true, antigravity: true });
+
+  useInput((input, key) => {
+    if (step === 'welcome' && key.return) {
+      setStep('storage');
+    } else if (step === 'confirm' && key.return) {
+      onComplete({
+        workspaceName,
+        workspacePath,
+        storageMode,
+        tools,
+        gitUser,
+      });
+    }
+  });
+
+  const handleStorageSelect = (item: { value: StorageMode }) => {
+    setStorageMode(item.value);
+    setStep('tools');
+  };
+
+  const handleToolsSelect = (item: { value: string }) => {
+    if (item.value === 'done') {
+      setStep('confirm');
+    } else if (item.value === 'copilot') {
+      setTools((t: typeof tools) => ({ ...t, copilot: !t.copilot }));
+    } else if (item.value === 'antigravity') {
+      setTools((t: typeof tools) => ({ ...t, antigravity: !t.antigravity }));
+    }
+  };
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Box borderStyle="round" borderColor="cyan" paddingX={2}>
+        <Text bold color="cyan">RRCE-Workflow Setup</Text>
+      </Box>
+
+      <Box marginTop={1}>
+        {step === 'welcome' && (
+          <Box flexDirection="column">
+            <Text>Welcome! Detecting your environment...</Text>
+            <Box marginTop={1} flexDirection="column">
+              <Text>
+                <Text color="green">✓</Text> Git user: <Text bold>{gitUser || '(not found)'}</Text>
+              </Text>
+              <Text>
+                <Text color="green">✓</Text> Workspace: <Text bold>{workspaceName}</Text>
+              </Text>
+            </Box>
+            <Box marginTop={1}>
+              <Text dimColor>Press Enter to continue...</Text>
+            </Box>
+          </Box>
+        )}
+
+        {step === 'storage' && (
+          <Box flexDirection="column">
+            <Text>Where should workflow data be stored?</Text>
+            <Box marginTop={1}>
+              <SelectInput items={storageModeItems} onSelect={handleStorageSelect} />
+            </Box>
+          </Box>
+        )}
+
+        {step === 'tools' && (
+          <Box flexDirection="column">
+            <Text>Which AI tools do you use?</Text>
+            <Box marginTop={1}>
+              <SelectInput
+                items={[
+                  { label: `[${tools.copilot ? 'x' : ' '}] GitHub Copilot (VSCode)`, value: 'copilot' },
+                  { label: `[${tools.antigravity ? 'x' : ' '}] Antigravity IDE`, value: 'antigravity' },
+                  { label: '───────────────', value: 'sep' },
+                  { label: 'Done', value: 'done' },
+                ]}
+                onSelect={handleToolsSelect}
+              />
+            </Box>
+          </Box>
+        )}
+
+        {step === 'confirm' && (
+          <Box flexDirection="column">
+            <Text bold color="green">Configuration Summary</Text>
+            <Box marginTop={1} flexDirection="column">
+              <Text>• Storage: <Text bold>{storageMode}</Text></Text>
+              <Text>• Copilot: <Text bold>{tools.copilot ? 'Yes' : 'No'}</Text></Text>
+              <Text>• Antigravity: <Text bold>{tools.antigravity ? 'Yes' : 'No'}</Text></Text>
+            </Box>
+            <Box marginTop={1}>
+              <Text dimColor>Press Enter to create configuration...</Text>
+            </Box>
+          </Box>
+        )}
+      </Box>
+    </Box>
+  );
+}