Bug Description
Hey speckit team — running into a recurring failure pattern that points at a structural gap worth fixing properly.
What's happening
Phase B ends with pushing packages to a custom NuGet feed that requires an API key and a feed URL — both sourced from environment variables defined in the constitution. When the agent
reaches the push step, it constructs the command from recall rather than from the constitution, gets the flags wrong, and hits a 403. The user has to intervene and point the agent back at the constitution it already read two steps ago.
Why it keeps happening
The constitution is a large document read once at plan time and then gone from context. Nothing keeps its executable rules available during execution. The tasks generated by /speckit-tasks make it worse — they describe governed operations in prose ("Push packages to feed") rather than emitting the exact syntax, so even the always-loaded task list doesn't help.
Three ideas that could close the gap
- Task bodies contain executable commands, not prose
/speckit-tasks runs right after the constitution has been read. That's the moment to stamp the exact command into the task body, parameterized with values already confirmed in the plan.
Tasks are surfaced in agent context every session — they're already the right delivery vehicle. Prose summaries throw that away.
- /speckit-compact generates a persistent constitution lattice
A command that distills the constitution's governed operations into a small, machine-readable lattice — just executable rules, no prose, no rationale. Runs automatically when the
constitution version changes and writes the output somewhere always-loaded.
- A constitution skill with auto-load triggers
A speckit-managed skill file whose frontmatter declares auto-load triggers for governed operations (dotnet pack, dotnet nuget push, git tag, any Phase B step). The skill body contains the compact lattice. When the agent is about to execute a governed operation, the correct syntax is already in context without any manual lookup.
Why MEMORY.md and CLAUDE.md aren't the answer
Both require the developer to maintain them. MEMORY.md is personal and project-specific — it's not something speckit can write to reliably across all users. CLAUDE.md is a configuration file the developer owns. Putting speckit's enforcement rules in either place means every developer who sets up a new project has to know to add them, which defeats the purpose.
The auto-load skill approach is different: the skill ships with speckit, gets generated from the project's own constitution, and loads automatically based on what the agent is about to do.
The developer configures nothing. The mechanism is universal even though the content is project-specific.
Disclaimer
Everything in this bug was surfaced through diagnostic debugging using a /why skill, which approximates the most likely reasoning behind a decision the AI made. It is of course prone to
failure — the skill can only infer, not observe. These are suggestions arrived at after many rounds of pushing back against the AI to confirm the reasoning held up under pressure. Take them as informed hypotheses, not certainties.
Steps to Reproduce
- Set up a speckit project with a constitution that defines a governed push operation requiring environment variable authentication
- Run /speckit-plan and /speckit-tasks to generate Phase B tasks
- Execute Phase B steps in order — or resume in a new session after some steps are already complete
- When the agent reaches the push step, observe whether it uses the correct command from the constitution or constructs one from recall
- If the constitution is no longer in active context, the agent will produce an incorrect command — wrong flags, missing credentials, or wrong source — and the push will fail
The failure is more likely to reproduce across sessions or late in a long session where the constitution has been compacted out of context.
Expected Behavior
The agent reads the push task, finds the exact command with the correct flags and env var references, and executes it successfully on the first attempt.
Actual Behavior
The agent constructs the command from recall — using the NuGet config source name instead of the feed URL env var and omitting the API key entirely. The push returns 403 Forbidden. The agent then goes to look up the constitution it should have read before acting.
Specify CLI Version
0.5.1-Dev0
AI Agent
Claude Code
Operating System
Windows Server 2019 Standard 10.0.17763
Python Version
3.11.14
Error Logs
Additional Context
No response
Bug Description
Hey speckit team — running into a recurring failure pattern that points at a structural gap worth fixing properly.
What's happening
Phase B ends with pushing packages to a custom NuGet feed that requires an API key and a feed URL — both sourced from environment variables defined in the constitution. When the agent
reaches the push step, it constructs the command from recall rather than from the constitution, gets the flags wrong, and hits a 403. The user has to intervene and point the agent back at the constitution it already read two steps ago.
Why it keeps happening
The constitution is a large document read once at plan time and then gone from context. Nothing keeps its executable rules available during execution. The tasks generated by /speckit-tasks make it worse — they describe governed operations in prose ("Push packages to feed") rather than emitting the exact syntax, so even the always-loaded task list doesn't help.
Three ideas that could close the gap
/speckit-tasks runs right after the constitution has been read. That's the moment to stamp the exact command into the task body, parameterized with values already confirmed in the plan.
Tasks are surfaced in agent context every session — they're already the right delivery vehicle. Prose summaries throw that away.
A command that distills the constitution's governed operations into a small, machine-readable lattice — just executable rules, no prose, no rationale. Runs automatically when the
constitution version changes and writes the output somewhere always-loaded.
A speckit-managed skill file whose frontmatter declares auto-load triggers for governed operations (dotnet pack, dotnet nuget push, git tag, any Phase B step). The skill body contains the compact lattice. When the agent is about to execute a governed operation, the correct syntax is already in context without any manual lookup.
Why MEMORY.md and CLAUDE.md aren't the answer
Both require the developer to maintain them. MEMORY.md is personal and project-specific — it's not something speckit can write to reliably across all users. CLAUDE.md is a configuration file the developer owns. Putting speckit's enforcement rules in either place means every developer who sets up a new project has to know to add them, which defeats the purpose.
The auto-load skill approach is different: the skill ships with speckit, gets generated from the project's own constitution, and loads automatically based on what the agent is about to do.
The developer configures nothing. The mechanism is universal even though the content is project-specific.
Disclaimer
Everything in this bug was surfaced through diagnostic debugging using a /why skill, which approximates the most likely reasoning behind a decision the AI made. It is of course prone to
failure — the skill can only infer, not observe. These are suggestions arrived at after many rounds of pushing back against the AI to confirm the reasoning held up under pressure. Take them as informed hypotheses, not certainties.
Steps to Reproduce
The failure is more likely to reproduce across sessions or late in a long session where the constitution has been compacted out of context.
Expected Behavior
The agent reads the push task, finds the exact command with the correct flags and env var references, and executes it successfully on the first attempt.
Actual Behavior
The agent constructs the command from recall — using the NuGet config source name instead of the feed URL env var and omitting the API key entirely. The push returns 403 Forbidden. The agent then goes to look up the constitution it should have read before acting.
Specify CLI Version
0.5.1-Dev0
AI Agent
Claude Code
Operating System
Windows Server 2019 Standard 10.0.17763
Python Version
3.11.14
Error Logs
Additional Context
No response