workflow/feynman/skills/SKILL.md

Workflow Bootstrap Skill

Description

Set up the issue-based workflow for a new project by cloning the template from https://git.fbrns.co/shoko/workflow.

This skill is automatically installed when you run pnpm run setup in a project cloned from the workflow template.

Use this skill when:

• Human asks to start a new project
• Human asks to "set up the workflow"
• Human asks to "apply the workflow template"
• Human asks to "initialize the issue-based workflow"
• Human is starting work in a new directory without the workflow structure

Workflow Template Location

• URL: https://git.fbrns.co/shoko/workflow
• Clone: https://git.fbrns.co/shoko/workflow.git
• Template repo contains:
  • /docs/workflow/ — INDEX.md, ISSUE-FORMAT.md, WORKFLOW.md, AGENT-PROMPTS.md
  • /.issues/ — INDEX.md, example issues
  • /.hooks/ — issue-linter.js (pre-commit validator)
  • /feynman/ — This skill + memory template

Steps

1. Check if workflow already exists

# Check if /docs/workflow/INDEX.md exists
ls -la /docs/workflow/INDEX.md 2>/dev/null && echo "exists" || echo "not found"

If workflow already exists, tell the human and ask if they want to re-initialize or just proceed.

2. Fetch template from Gitea

# Clone the template repo
git clone https://git.fbrns.co/shoko/workflow.git /tmp/workflow-template

# Or download as archive
curl -L https://git.fbrns.co/shoko/workflow/archive/main.tar.gz | tar -xz -C /tmp/

3. Copy template structure to current directory

# Copy workflow docs
cp -r /tmp/workflow-template/docs/workflow/ ./docs/

# Copy issue structure (but not example files unless needed)
mkdir -p ./.issues
cp /tmp/workflow-template/.issues/INDEX.md ./.issues/

# Copy hooks
mkdir -p ./.hooks
cp /tmp/workflow-template/.hooks/issue-linter.js ./.hooks/

# Copy package.json scripts if they exist and merge with existing
if [ -f /tmp/workflow-template/package.json ]; then
  # Merge workflow-scripts into existing package.json
  echo "Template has package.json - review scripts manually"
fi

4. Initialize git hooks (pre-commit)

# Make hook executable
chmod +x ./.hooks/issue-linter.js

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

# Or: install via husky if project uses it
# npx husky add .husky/pre-commit "node ./.hooks/issue-linter.js"

5. Verify setup

# Check structure
ls -la docs/workflow/
ls -la .issues/
ls -la .hooks/
ls -la .git/hooks/pre-commit

# Test hook manually
echo "Testing pre-commit hook..."
# Create a dummy change and try to commit

6. Create first issue index if needed

If /.issues/INDEX.md exists, review it and update if needed. If not, create it.

7. Summary for human

Tell the human:

• What was copied
• Where to find the docs
• How to start using it
• That the pre-commit hook is now active

Example output:

Workflow template installed. Structure:

  docs/workflow/      ← READ THIS FIRST (INDEX.md)
  .issues/           ← Your issues live here
  .hooks/            ← Pre-commit validator active

Pre-commit hook is installed. Any code change without a valid issue file will be rejected.

To start working:
1. Read docs/workflow/INDEX.md
2. Create your first issue in .issues/
3. Follow the workflow stages defined there

Let me know when you're ready to create your first issue.

Error Handling

Error	What to do
Gitea repo not accessible	Tell human, offer to create structure manually from documentation
.git/hooks/ already has pre-commit	Ask human whether to overwrite or merge
Not in a git repo	Tell human "This requires a git repository. Run git init first."
node not available for hook	Fall back to bash-based validator or skip hook with warning

Human Prompts That Trigger This Skill

• "feynman, start a new project"
• "set up the workflow"
• "apply the template"
• "initialize the issue-based workflow"
• "let's work on something new"