# Workflow Template

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

## Quick Start

1. **Clone this repo** into your new project
2. **Install dependencies**: `pnpm install` (or npm, yarn)
3. **Run setup**: `pnpm run setup` (installs pre-commit hook)
4. **Read the docs**: See `docs/workflow/INDEX.md`
5. **Start working**: See `docs/workflow/WORKFLOW.md`

## 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

## 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
└── package.json         # Setup scripts
```

## Setup

```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

# Install dependencies
pnpm install

# Setup pre-commit hook
pnpm run setup

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

## 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)

## License

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