Proposal: Introduce `index.md` for directory abstraction and backward compatibility

[sherzat3]

Problem

The current Conductor extension relies on hardcoded file paths and names (e.g., conductor/plan.md, conductor/tracks/spec.md) within its instructions. This rigidity makes it difficult to evolve the generated conductor/ file structure or hierarchy in future updates without breaking backward compatibility for existing projects or extensions.

The Proposal

Introduce an index.md file at each hierarchical level within the generated conductor/ directory.

Functionality:

• Directory Manifest: Each index.md will serve as a Table of Contents (TOC), dynamically describing and linking to all relevant files and folders within its directory.
• Single Source of Truth: All extension instructions will be updated to read index.md first to resolve file paths, rather than assuming fixed filenames.

Example Structure

conductor/index.md

# Project Context
- [Product Definition](./product.md)
- [Workflow](./workflow.md)
- [Tracks Registry](./tracks.md)

conductor/tracks/<track_id>/index.md

# Track <id> Context
- [Specification](./spec.md)
- [Implementation Plan](./plan.md)
- [Metadata](./metadata.json)

Benefits

1. Backward Compatibility: We can rename files or move them into subfolders in future versions. As long as the index.md is updated to point to the new locations, the extension (and LLM) will find them without code changes.
2. Modularity: Allows for different project structures (e.g., Greenfield vs. Brownfield) to coexist while presenting a unified interface via index.md.
3. Context Awareness: Explicitly listing files in an index helps the LLM understand the relationship between artifacts better than a simple directory listing.

---

Request for Comments

We'd love to hear the community's thoughts on this proposal! specifically:

• Does this abstraction align with your current workflows?
• Are there any potential downsides or edge cases we missed?

Please share your feedback below!

[amirkiarafiei]

Great idea!