genichin
9339d3d503
git-subtree-dir: .stage-pilot git-subtree-split: 2c0510c68add43c50adcdedb30c174e68e730395
62 lines
2.0 KiB
Markdown
62 lines
2.0 KiB
Markdown
# 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
|