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

# 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
• Issue Format
• Step-by-Step Workflow
• Agent Prompts

License

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