Squashed '.stage-pilot/' content from commit 2c0510c

git-subtree-dir: .stage-pilot git-subtree-split: 2c0510c68add43c50adcdedb30c174e68e730395
2026-06-03 08:56:02 +00:00
commit 9339d3d503
100 changed files with 8843 additions and 0 deletions
@@ -0,0 +1,61 @@
+# 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