FILE_PATH_CONVENTION.md

File Path Convention for Work Item Descriptions

Purpose

The wl next --groups/-g grouping feature determines parallel-work safety by extracting file paths from work item descriptions. To make this work reliably, all intake_complete work items should include a **Key Files:** or ## Key Files section listing the files the work item will touch.

Convention Specification

Format

Add a **Key Files:** or ## Key Files section near the end of the work item description with bullet-pointed file paths:

**Key Files:**
- `path/to/file.ext`
- `another/file.ts`
- `docs/guide.md`

A Markdown heading (without a trailing colon) is also accepted:

## Key Files
- `path/to/file.ext`
- `another/file.ts`
- `docs/guide.md`

Rules

1. Section header: Use **Key Files:** (bold with colon) or ## Key Files (Markdown heading without colon). The header is case-insensitive (key files:, Key Files:, KEY FILES:) — any casing works. Bold markers are optional but recommended. A trailing colon after key files is also optional — the parser accepts both Key Files: and Key Files.

2. Bullet items: List paths as Markdown bullet items using - or * . Each line starting with - or * after the header is processed as a path candidate.

3. Backticks: Paths may be wrapped in backticks or plain text:

   • - `src/commands/next.ts` (recommended, visually distinct)
   • - src/commands/next.ts (also valid)

4. Trailing description: Paths with backticks may have descriptive text after the closing backtick. The parser extracts only the text between backticks as the path:

   • - `src/commands/next.ts` — New file for next command
   • - `src/commands/helpers.ts`: Shared helpers
   • - `src/foo.ts` (some context)

5. Valid path criteria: Each extracted path must:

   • Contain at least one / (indicating a file in a directory)
   • End with a file extension (e.g., .ts, .md, .json)
   • Not be a URL (http://..., https://...)

6. Single section: Only the first **Key Files:** section in the description is processed. Any subsequent sections are ignored.

7. Section termination: The parser stops at the next Markdown heading (#, ##, ###) or the next bold section header (e.g., **Risks:**).

Examples

Valid

## Summary

Implement the new grouping feature.

**Key Files:**
- `src/commands/grouping.ts`
- `src/commands/helpers.ts`
- `tests/grouping-utility.test.ts`

## Risks

None identified.

Key Files:
- src/commands/next.ts
- docs/CLI.md

Invalid

Missing section entirely:

## Summary

Do the thing. No file paths listed.

Section exists but no valid paths:

**Key Files:**
- https://example.com
- Some random text

When to Include

Stage	Required?
idea	No (optional)
intake_complete	Should include
plan_complete	Should include (groups items)
in_progress	Optional
in_review	No

Programmatic Access

The extractFilePaths() function in src/commands/helpers.ts implements the extraction logic. It is shared between:

• The wl next --groups/-g grouping algorithm
• The wl doctor file-paths subcommand
• The automatic advisory check on transition to intake_complete

Related

• CLI.md — wl next and wl doctor command documentation
• wl doctor file-paths — On-demand validation
• Work Item Descriptions — Description format guidance