trex-core/skills/draft-req/references/template-path-resolution.md

Template Path Resolution for draft-req

Use this reference when StagePilot is installed in different physical locations across agents or repositories.

Core rule

Do not treat one physical path as the canonical template location for every agent.

Instead:

• treat stage-pilot/templates/... as the stable logical template path
• resolve that logical path against the active workspace or agent installation
• keep template source paths separate from generated target paths under docs/srs/

Logical template paths

For draft-req, the logical template sources are:

• stage-pilot/templates/srs/index.md
• stage-pilot/templates/srs/req-template.md

These names are portable across Hermes Agent, GitHub Copilot, Claude, and similar environments. The physical path may differ.

Physical path resolution order

When resolving a logical template path, check candidates in this order:

1. Workspace-local / subtree install: .stage-pilot/templates/...
2. Hermes external install: ~/.stage-pilot/templates/...

Prefer the current workspace's installed copy over a user-level fallback.

Source vs target distinction

Keep these separate:

• Template source: stage-pilot/templates/... resolved to one physical path above
• Generated targets: docs/srs/index.md and docs/srs/<Type>/req-XXX_<slug>.md

Do not describe a generated docs/srs/... file as if it were the template source.

Ambiguity rule

If multiple physical candidates exist:

• prefer the highest-priority path in the resolution order above
• do not silently mix sources from different installs
• report which physical path was used when ambiguity could matter

Durable pitfall

A common portability mistake is to hardcode only one of these:

• .stage-pilot/templates/...
• ~/.stage-pilot/templates/...

That works for one install shape but breaks on another machine or agent. The durable pattern is:

• logical path in the skill
• resolution rule in the workflow
• generated target path documented separately