Workflow Template

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

Quick Start

# 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 if missing, dependencies, and pre-commit hook)
pnpm run setup

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

That's it. The setup script handles everything.

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

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

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

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:

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

Troubleshooting

"pnpm not found" during setup

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

# 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

# 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