Filesystem

Why this tracker exists

Every other tool in the PM tools overview starts with an account. Sign up, create a workspace, provision an API key, wire an MCP server, and only then can pair file your first story. That is a reasonable price for a team. It is a poor one for a developer trying pair out on a Saturday, for anyone working offline, and for an air-gapped environment where "create an account" is not a step that exists.

The filesystem tracker removes the account. Your backlog is Markdown in your repository; an item's status is the directory it sits in, so a transition is a git mv and your board history is your commit history. Nothing to provision, nothing to reach over the network, and no second system that can disagree with your code about what shipped.

That choice has one consequence worth stating up front, because it decides how you configure the rest of your project: a directory of Markdown files hosts no pull requests. pair used to read a single pm-tool field for both backlog work and code work, which quietly assumed the tracker also owned your repository, true on GitHub, false here.

So a filesystem project is a two-tool project by construction: declare a code host alongside it (per ADR-018) and pair routes item state to the files and branch/PR/review work to that host.

Skip the declaration and pair stops with a setup pointer before its first PR operation, rather than routing a pull request at a folder.

Configuration

Add these lines to .pair/adoption/tech/way-of-working.md:

- Filesystem is adopted for project management, using markdown files and folder organization.
  The backlog is managed in `.pair/adoption/product/backlog/` directory structure.
  See `.pair/knowledge/guidelines/collaboration/project-management-tool/README.md` for usage.
 
## Git Workflow
 
- `code-host`: `github` - repository `<org>/<repo>`.
- `base-branch`: `main`.

Item and state operations go to the files; branch, PR, review and merge operations go to the code host. ## Git Workflow is not optional here: a directory hosts no pull requests, so there is nothing for pair to fall back to when the field is absent.

Prerequisites

• A pair-enabled project (pair-cli install completed)
• No PM tool account, API key or MCP server: the backlog is files in your repo
• An account on the code host you declare above (GitHub by default), because that is where branches, PRs and review live: a self-hosted or on-prem git host is a valid code-host too: pair ships a KB implementation guide for GitHub and Azure DevOps only, so for anything else it warns once and proceeds best-effort through that host's own CLI/API, which is never a HALT by itself

This is the zero-PM-dependency option: every work item lives in your repository as version-controlled Markdown, and the only external account is the one your pull requests already needed. Ideal for solo developers, offline backlog work, or projects that don't need a separate PM tool.

Mapping Model

pair maps its work hierarchy to directories and files:

pair                    Filesystem
────                    ──────────
Initiative          →   Markdown file in 01-initiatives/
Epic                →   Markdown file in 02-epics/<status>/
User Story          →   Markdown file in 03-user-stories/<status>/
Task                →   Checklist item in story file

Directory Structure

.pair/adoption/product/backlog/
├── 01-initiatives/
│   └── 2025/
│       ├── initiative-auth-system.md
│       └── initiative-api-v2.md
├── 02-epics/
│   ├── not-started/
│   ├── in-progress/
│   │   └── epic-user-registration.md
│   ├── under-review/
│   └── completed/
└── 03-user-stories/
    ├── not-started/
    │   └── story-signup-form.md
    ├── in-progress/
    ├── under-review/
    └── completed/

How It Works

• Initiatives are Markdown files organized by year
• Epics and stories are Markdown files organized by status folder
• Tasks are checkbox items inside the story file, not separate files
• Status tracking is managed by moving files between status directories
• Everything is version-controlled: Git history shows exactly what changed and when

Status Transitions

The PR itself never lives here: a filesystem tracker hosts no repositories or pull requests, so declare a code host in way-of-working.md → ## Git Workflow. The rows above are the item-state effects of PR events that happen on that host.

Templates

Each work item type uses the standard pair templates:

First-Run Example

After configuring way-of-working.md, run a process skill:

/pair-process-plan-stories #epic-user-registration

Expected output:

STORIES CREATED:
├── story-signup-form.md        → 03-user-stories/not-started/
├── story-login-flow.md         → 03-user-stories/not-started/
├── story-password-reset.md     → 03-user-stories/not-started/
└── Epic: 3 stories created in not-started/

pair creates Markdown files using the story template, places them in not-started/, and adds task checklists to each file.

Verifying the Setup

1. Check that .pair/adoption/product/backlog/ directory structure exists
2. Verify story files appear in 03-user-stories/not-started/
3. Each file should follow the user story template with filled-in sections
4. git status shows the new files ready to commit

When to Upgrade

Consider switching to GitHub Projects or Linear when:

• Multiple team members need to see the board simultaneously
• You want automated status tracking without manual file moves
• You need reporting and velocity metrics

Switching is painless: update way-of-working.md and pair starts using the new tool. Your Knowledge Base and adoption files stay the same.

Related

• PM Tools overview: choosing the right tool
• GitHub Projects: GitHub-native option
• Linear: dedicated PM tool option