Skip to content

Enhance proposal guidelines in slash-command-templates.ts #306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TabishB merged 4 commits into from
Nov 19, 2025
Merged

Enhance proposal guidelines in slash-command-templates.ts #306

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
091d1fc
Enhance proposal guidelines in slash-command-templates.ts
jax-max Nov 14, 2025
34a9ed9
Update proposal guidelines in slash-command-templates.ts to clarify t…
jax-max Nov 14, 2025
a39b562
Refine proposal and apply steps in slash-command-templates.ts
jax-max Nov 17, 2025
f80e99a
Merge branch 'feat/ImproveGenCodeQuality' of github.com:jax-max/OpenS…
jax-max Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions src/core/templates/slash-command-templates.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ const baseGuardrails = `**Guardrails**
- Keep changes tightly scoped to the requested outcome.
- Refer to \`openspec/AGENTS.md\` (located inside the \`openspec/\` directory—run \`ls openspec\` or \`openspec update\` if you don't see it) if you need additional OpenSpec conventions or clarifications.`;

const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.`;
const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
Copy link
Contributor

@TabishB TabishB Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jax-max How has this updated instruction been working for you? Do you feel like this has COMPLETELY stopped the agent from writing code?

Will try it out, but keen to hear your experience first?

Copy link
Contributor

@TabishB TabishB Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mainly asking to just get a sense of whether this actually works, i'm ok with the change itself, because I agree that it's a problem.

Copy link
Contributor Author

@jax-max jax-max Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TabishB Hi there! Our team (not only me) has noticed that code automatically starts being written during the proposal phase. We’ve checked the system prompt of the tool being used and found no issues—it’s a rather odd problem.
Adding a clarifying note here might theoretically help a bit, but the LLM will probably still not behave as intended, haha.
We’re wondering if you’ve encountered this issue before?

- Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.`;

const proposalSteps = `**Steps**
1. Review \`openspec/project.md\`, run \`openspec list\` and \`openspec list --specs\`, and inspect related code or docs (e.g., via \`rg\`/\`ls\`) to ground the proposal in current behaviour; note any gaps that require clarification.
Expand All @@ -14,7 +15,8 @@ const proposalSteps = `**Steps**
4. Capture architectural reasoning in \`design.md\` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
5. Draft spec deltas in \`changes/<id>/specs/<capability>/spec.md\` (one folder per capability) using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant.
6. Draft \`tasks.md\` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.`;
7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.
Copy link
Contributor

@TabishB TabishB Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting you decided to add this here as well. Any particular reason?

Copy link
Contributor Author

@jax-max jax-max Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to clarify again—our model’s compliance is really subpar. Feel free to delete this if you find it redundant.

Remember: This is a design phase. Do not write any implementation code.`;

const proposalReferences = `**Reference**
- Use \`openspec show <id> --json --deltas-only\` or \`openspec show <spec> --type spec\` to inspect details when validation fails.
Expand All @@ -23,7 +25,7 @@ const proposalReferences = `**Reference**

const applySteps = `**Steps**
Track these steps as TODOs and complete them one by one.
1. Read \`changes/<id>/proposal.md\`, \`design.md\` (if present), and \`tasks.md\` to confirm scope and acceptance criteria.
1. Read \`openspec/project.md\` to understand project conventions, then read \`changes/<id>/proposal.md\`, \`design.md\` (if present), and \`tasks.md\` to confirm scope and acceptance criteria.
Copy link
Contributor

@TabishB TabishB Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, I'm not too sure if this makes sense. The idea is using the project context to create the plan and then using the plan to implement.

project context -> plan -> implement

If you've used the project context to create the plan then you most likely don't need to read the context again during the implementation stage. The plan should already be created with the project context in mind.

So IMO, it's a bit redundant here to read the context again and possibly using more tokens than we need.

If you've had a different experience here, let me know!

Copy link
Contributor Author

@jax-max jax-max Nov 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@TabishB Greetings! It may be that the limited number of chapters in the OpenSpec document template leads to significant information loss during the project context → plan phase, which in turn affects the code accuracy in the plan → implement phase.
From our practice, a simple fix is to revisit and re-read the project context during the plan → implement phase. A more elegant solution could be supporting custom plan templates : #307
I'd love to hear your thoughts. Looking forward to your reply!

2. Work through tasks sequentially, keeping edits minimal and focused on the requested change.
3. Confirm completion before updating statuses—make sure every item in \`tasks.md\` is finished.
4. Update the checklist after all work is done so each task is marked \`- [x]\` and reflects reality.
Expand Down
Loading