-
Notifications
You must be signed in to change notification settings - Fork 961
docs: add guidance for populating project-level context #241
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.
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
docs: add guidance for populating project-level context #241
Conversation
Add documentation for the optional step of populating project.md with project details, tech stack, and conventions after running openspec init. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
WalkthroughREADME.md adds an optional "Fill out project details" section with an example prompt for project context, and replaces the concise example in "Create Your First Change" with a detailed, stepwise workflow (Draft Proposal → Verify & Review → Refine Specs → Implement Change → Archive) including sample commands and dialog. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant CLI as OpenSpec CLI (docs)
participant Repo as Repo / Spec Files
rect rgb(230,245,255)
Note right of Dev: Step 1 — Draft the Proposal
Dev->>CLI: run "openc spec new" (draft)
CLI->>Repo: create draft proposal file
Repo-->>Dev: draft file created
end
rect rgb(240,255,230)
Note right of Dev: Step 2 — Verify & Review
Dev->>CLI: run "openc spec verify" / request review
CLI->>Dev: display checks / reviewer prompts
Dev->>Repo: update proposal after review
end
rect rgb(255,250,230)
Note right of Dev: Step 3 — Refine the Specs
Dev->>CLI: run "openc spec refine" (iterate)
CLI->>Repo: update spec artifacts
end
rect rgb(255,235,240)
Note right of Dev: Step 4 — Implement & Archive
Dev->>Repo: implement changes, mark complete
CLI->>Repo: archive completed change entry
Repo-->>Dev: confirmation
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Comment |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actionable comments posted: 1
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
PR: Fission-AI/OpenSpec#0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-10-22T06:05:06.604Z
Learning: Applies to openspec/project.md : Document project conventions in openspec/project.md and review it before starting work
🪛 markdownlint-cli2 (0.18.1)
README.md
156-156: Heading style
Expected: atx; Actual: atx_closed
(MD003, heading-style)
160-160: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
README.md (2)
158-166: Content quality: clear guidance for project context setup.The new section successfully addresses issue #234 by providing straightforward instructions for populating project-level context. The suggested prompt is concrete and actionable, and the explanation of the section's purpose aligns well with the learning guideline on documenting project conventions in
openspec/project.md.
167-232: Excellent workflow documentation with clear examples.The expanded "Create Your First Change" section transforms a brief overview into a comprehensive, step-by-step guide. The 5-step breakdown (Draft → Verify & Review → Refine Specs → Implement → Archive) with realistic dialog examples and concrete commands is well-structured and highly usable. The dual-track approach showing both slash command shortcuts and natural language alternatives is a thoughtful touch for tool compatibility.
- Change heading to "Optional: Populate Project Context" for consistency - Fix double space typo in "After openspec init" - Explicitly reference openspec/project.md file - Enhance explanation of project.md purpose 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
TabishB
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks this is fine, it follows what the current project convention expects, comment below is mainly just for me to re-evaluate the value of this file.
| "Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions" | ||
| ``` | ||
|
|
||
| Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think I need to re-think about having or adding conventions here. I feel this maybe collides with what is expected to be in an AGENTS.md or CLAUDE.md file usually so we might be replicating conventions across multiple docs.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good point. Thanks.
Closes #234
Add documentation for the optional step of populating
project.mdwith project details, tech stack, and conventions after running openspec init.🤖 Generated with Claude Code
Summary by CodeRabbit