Board folder structure

Single git project

Board under the product repo at <project>/taskmark/:

my-app/
└── taskmark/
    ├── .gitignore      # ignores REPOS.md and .reports/
    ├── REPOS.md        # local only — generated, not committed
    ├── .reports/       # /tkmd-reportme output — local only
    └── epics/
        └── E-MM-k7m2p9b3-user-auth/
            ├── epic.md
            └── stories/
                └── S-MM-n4q8w1a2-login/
                    ├── story.md
                    └── items/
                        ├── T-MM-a8f31c2d-api.md
                        └── B-MM-f8h1j4c5-token.md

Multiple git projects

Dedicated sibling <common>-taskmark — repo root is the board (no nested taskmark/). Product repos stay clean.

acme-taskmark/
├── .gitignore
├── REPOS.md        # local only
├── .reports/       # /tkmd-reportme — local only
├── epics/
└── .git/

Never copy the board into every product repo. /tkmd-init (and local generation) refresh REPOS.md on this machine.

What is not in git

The UI scans epics/. Committed boards do not include a generated index, sizing seed file, velocity file, or board README. CHANGELOG.md at the board root is optional and is written only by /tkmd-changelog and /tkmd-version— not into the README. REPOS.md and .reports/ are gitignored: REPOS.md holds absolute local paths, and /tkmd-reportme writes personal reports under .reports/.

IDs and file conventions

• IDs keep a type prefix E, S, T, or B plus a collision-resistant token (not a global sequential counter). Historical sequential IDs such as T-001 remain valid
• Folder slug: {id}-{kebab-title}
• Tasks/bugs live under a story’s items/ or an epic’s items/ (epic-direct — no story required)
• Plan and do write only new or target leaf files. Parent child lists, status, points, people, dates, and logs are derived in the UI at read time

Hierarchy fit

/tkmd-plan searches open and done work first. New tasks and bugs attach explicitly under the best-fitting existing story or epic; new stories attach under a fitting epic. A new epic is created only for a distinct initiative that fits nowhere else.

Related: File specification (frontmatter and section templates), Workflows, Sizing.