[Feature] inject project context into all skills and enforce constraints#703
[Feature] inject project context into all skills and enforce constraints#703lsmonki wants to merge 1 commit intoFission-AI:mainfrom
Conversation
Add `openspec instructions --context` CLI command to expose project context from config.yaml independently of any change. Update all skill templates (explore, continue, apply, ff, archive, bulk-archive, sync, verify) to load project context at session start and follow it as mandatory constraints. Strengthen enforcement language from "IMPORTANT" to "MANDATORY" for context, rules, and instruction fields across all skill and opsx command templates. Inject project context into apply instructions output via a new `context` field.
📝 WalkthroughWalkthroughThis PR introduces a Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/core/templates/skill-templates.ts (1)
2115-2127:⚠️ Potential issue | 🟡 MinorOpsx FF command template is missing the MANDATORY guardrail block present in the FF skill template.
The FF skill template (
getFfChangeSkillTemplate, lines 767-771) includes a**MANDATORY**block reinforcing thatcontext,rules, andinstructionmust be followed and not copied. The corresponding opsx command template here omits that block, though it does have MUST language earlier (lines 2082-2090).Per the skill-context-enforcement spec (line 52-57), generated slash commands should reflect the same enforcement language as their skill templates.
Proposed fix — add MANDATORY block to opsx:ff guidelines
**Artifact Creation Guidelines** - Follow the \`instruction\` field from \`openspec instructions\` for each artifact type - The schema defines what each artifact should contain - follow it - Read dependency artifacts for context before creating new ones - Use the \`template\` as a starting point, filling in based on context +- **MANDATORY**: \`context\`, \`rules\`, and \`instruction\` from the instructions output are constraints you MUST follow + - \`context\`: Project-level constraints (tech stack, conventions) — follow them, do NOT copy into the artifact + - \`rules\`: Artifact-specific rules — follow them, do NOT copy into the artifact + - \`instruction\`: Directives for how to create this artifact — follow them + - Do NOT copy \`<context>\`, \`<rules>\`, \`<project_context>\` blocks into the artifact **Guardrails**
🧹 Nitpick comments (1)
src/commands/workflow/instructions.ts (1)
515-533: Consider extracting the shared config-reading pattern.Lines 519-524 duplicate the pattern from lines 396-401 (
readProjectConfig+ extract context + try/catch). Both could share a small helper likereadProjectContext(projectRoot): string | null. Low priority since there are only two call sites and the return types intentionally differ (nullvsundefined).
Greptile OverviewGreptile SummaryThis PR ensures all skills have access to project context from Major changes:
Implementation quality:
Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant Agent as AI Agent/Skill
participant CLI as openspec CLI
participant Config as readProjectConfig()
participant Instructions as generateInstructions()
participant ApplyInst as generateApplyInstructions()
Note over Agent,ApplyInst: Context-only mode (Explore, Archive, Sync, etc.)
Agent->>CLI: openspec instructions --context --json
CLI->>Config: Read config.yaml
Config-->>CLI: {context: "..."}
CLI-->>Agent: {context: "..."}
Note over Agent,ApplyInst: Artifact mode (Continue, FF, New, etc.)
Agent->>CLI: openspec instructions <artifact> --change <name> --json
CLI->>Instructions: generateInstructions()
Instructions->>Config: Read config.yaml
Config-->>Instructions: {context, rules}
Instructions-->>CLI: {context, rules, template, instruction, ...}
CLI-->>Agent: Full artifact instructions
Note over Agent,ApplyInst: Apply mode (Apply, Verify)
Agent->>CLI: openspec instructions apply --change <name> --json
CLI->>ApplyInst: generateApplyInstructions()
ApplyInst->>Config: Read config.yaml (NEW)
Config-->>ApplyInst: {context}
ApplyInst-->>CLI: {context, tasks, progress, ...}
CLI-->>Agent: Apply instructions with context
|
TabishB
left a comment
TabishB
left a comment
There was a problem hiding this comment.
I don't think all skills need to get/retrieve the project context. The context field is mainly to drive the creation of the change proposal.
Even for apply, if your change proposal was created with the context in mind, the tasks, instructions, etc., should already have this baked into the plan as well.
| @@ -0,0 +1,120 @@ | |||
| ## Context | |||
|
|
|||
| Project context (`config.yaml` → `context` field) reaches only skills that call `openspec instructions <artifact>` — Continue, FF, New, Onboard. Skills that call `openspec instructions apply` (Apply, Verify) or no instructions at all (Explore, Archive, Bulk-archive, Sync) operate blind to project constraints. | |||
There was a problem hiding this comment.
Why would all skills need this? the context field is is meant to help guide planning or creating the change proposal?
I agree that yes, the Explore skill could benefit from this.
But do the rest actually benefit from this? i.e archive? sync, bulk-archive??
There was a problem hiding this comment.
When I implemented this, I was already thinking ahead to the hook system from my other PR. My intention was to avoid introducing another refactor later if hooks start requiring contextual information.
You're right — at the moment there are no hooks, so strictly speaking the additional context is not required.
Also, in my current setup the context is not only about providing generic project metadata (like “this is a TS project with Node”). It explicitly instructs the agent to review the existing specs under specs/ before making changes, to ensure compliance with previous architectural decisions, conventions, constraints...
So the goal is consistency with existing specs, not just additional descriptive context.
That said, I understand that in the current state it may not be strictly necessary, and I’m fine simplifying it if you prefer to introduce it later.
2 participants
Summary
openspec instructions --contextCLI command to expose project context fromconfig.yamlindependently of any change or artifactcontextfieldcontext,rules, andinstructionfields across all skill and opsx command templatesMotivation
The
config.yamlcontextfield defines critical project constraints (tech stack, conventions, cross-platform rules), but not all skills had access to it. Explore mode, archive, bulk-archive, and sync operated without project context entirely. Other skills used softer language ("constraints for you") that agents sometimes ignored.Changes
CLI (
src/cli/index.ts,src/commands/workflow/instructions.ts)--contextflag onopenspec instructionsthat returns project context without requiring a change or artifact--change,--schema, or an artifact argument--jsonoutput for agent consumptionApply instructions (
src/commands/workflow/instructions.ts,src/commands/workflow/shared.ts)generateApplyInstructions()now reads and returns project context in thecontextfieldprintApplyInstructionsText()outputs context in a<project_context>block with AI-directed suppression commentSkill templates (
src/core/templates/skill-templates.ts)openspec instructions --context --jsonat session startinstructionfield elevated to same mandatory status ascontextandrulesDocs (
docs/cli.md)openspec instructions: artifact, apply, context-only--contextand--context --jsonTests (
test/commands/artifact-workflow.test.ts)contextInstructionsCommandwith and without config--contextflag exclusivity validationRelated issues
Summary by CodeRabbit
Release Notes
New Features
--contextflag for instructions command outputs project context from config.yaml in text or JSON formatDocumentation
Tests