# Workflow Template

A portable, file-based issue tracking and development workflow for teams.

## Quick Start

```bash
# Clone this repo into your new project
git clone https://git.fbrns.co/shoko/workflow.git my-new-project
cd my-new-project

# Remove git history (optional, for a fresh start)
rm -rf .git

# Initialize git
git init

# Setup (installs pnpm, dependencies, pre-commit hook, and Feynman configs)
pnpm run setup

# Remove this README (it's the template's README)
rm README.md
```

**That's it.** The setup script handles everything—including installing the Feynman skill if Feynman is detected.

## What This Is

- **Issues are files** in `/.issues/`, not in external trackers
- **Issues are tracked by git**, alongside the code they affect
- **Agents think out loud** in issue files, making reasoning visible
- **Humans approve reasoning**, not code line-by-line
- **Pre-commit hooks enforce** issue format before any commit
- **Feynman integration** for automatic workflow bootstrapping

## Feynman Integration

If Feynman is installed on your system, the setup script will automatically:

1. Detect the Feynman installation
2. Install the `workflow-bootstrap` skill
3. Create `.feynman/memory.md` with workflow preferences

This gives you a two-layer nudge system:
- **Skill** (manual trigger): Say "feynman, set up the workflow" for new projects
- **Memory** (automatic nudge): Feynman reminds you if you forget

## Requirements

- **Node.js** (recommended: https://nodejs.org)
  - If you don't have Node.js, the setup script will install `pnpm` using `corepack` or `npm`
- **Git**
- **Feynman** (optional, for automatic workflow bootstrapping)

No other dependencies required for the workflow itself.

## File Structure

```
/
├── docs/workflow/         # Workflow documentation
│   ├── INDEX.md          ← Start here
│   ├── ISSUE-FORMAT.md   ← Issue file format
│   ├── WORKFLOW.md       ← Step-by-step process
│   └── AGENT-PROMPTS.md  ← Copy-paste agent prompts
├── .issues/              # Issue files
│   ├── INDEX.md          # List of all issues
│   └── example/          # Example issues
├── .hooks/               # Pre-commit validators
│   └── issue-linter.js   # Issue format validator
├── scripts/
│   └── setup.sh          # Setup script
└── package.json         # Setup commands
```

## Setup Command

```bash
pnpm run setup
```

This will:
1. Check for `pnpm`, install it if missing (via corepack or npm)
2. Install dependencies
3. Install the pre-commit hook in `.git/hooks/`

If Node.js isn't installed, the script will tell you to install it first.

## Manual Setup (Without pnpm)

If you prefer not to use pnpm:

```bash
# 1. Install Node.js from https://nodejs.org

# 2. Install pnpm
npm install -g pnpm

# 3. Install dependencies
pnpm install

# 4. Manually install pre-commit hook
mkdir -p .git/hooks
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
node .hooks/issue-linter.js
EOF
chmod +x .git/hooks/pre-commit
```

## For Teams

This template is maintained at: https://git.fbrns.co/shoko/workflow

To update the template for all projects:
1. Pull latest changes from this repo
2. Merge into your project

## Documentation

- [Workflow Overview](docs/workflow/INDEX.md)
- [Issue Format](docs/workflow/ISSUE-FORMAT.md)
- [Step-by-Step Workflow](docs/workflow/WORKFLOW.md)
- [Agent Prompts](docs/workflow/AGENT-PROMPTS.md)

## Troubleshooting

### "pnpm not found" during setup

The setup script tries to install pnpm automatically. If it fails:

```bash
# Install Node.js first
# Then enable pnpm via corepack
corepack enable
corepack prepare pnpm@latest --activate

# Or install via npm
npm install -g pnpm

# Re-run setup
pnpm run setup
```

### Pre-commit hook not running

```bash
# Make sure the hook is executable
chmod +x .git/hooks/pre-commit

# Test the hook manually
node .hooks/issue-linter.js
```

### "git commit rejected" errors

The pre-commit hook is rejecting your commit because:
- Code changed without a corresponding issue file
- Issue file is missing required fields
- Issue has `done` status but is incomplete

Fix the issue file and try again. Run `node .hooks/issue-linter.js` for details.

## License

Internal use. See https://git.fbrns.co/shoko/workflow