Skip to content

Conversation

@harikrishnan83
Copy link
Contributor

@harikrishnan83 harikrishnan83 commented Oct 26, 2025

Closes #234

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

Summary by CodeRabbit

  • Documentation
    • Added an optional project-details step during initialization to capture tech stack and conventions, including an example prompt to populate project context.
    • Expanded the "Create Your First Change" guide into a detailed step-by-step workflow (Draft, Verify & Review, Refine Specs, Implement, Archive) with sample commands and dialog.

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>
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Oct 26, 2025

Walkthrough

README.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

Cohort / File(s) Summary
Documentation
README.md
Adds an optional "Fill out project details such as tech stack and conventions" section with an example prompt; expands "Create Your First Change" into a granular, step-by-step workflow (Draft the Proposal, Verify & Review, Refine the Specs, Implement the Change, Archive the Completed Change) with sample commands and example dialog.

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
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

  • Documentation-only, single-file change.
  • Suggested review focus:
    • Verify example commands and dialog accurately reflect CLI/product behavior.
    • Check clarity and sequencing of the step-by-step workflow for newcomers.
    • Ensure the example prompt aligns with project-level guidance needs (e.g., non-negotiables, architectural style).

Poem

🐰 I hopped through lines of README bright,
A prompt to share the project's light.
From draft to review, each step in tune,
I tap my paw and hum a tune.
Hop on—new changes bloom by moon.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
Out of Scope Changes Check ❓ Inconclusive The primary change—adding a new section with guidance for populating project-level context—is clearly in scope for issue #234, which asks for documentation on setting up project-level guidance. However, the changeset also extends the "Create Your First Change" section with a detailed step-by-step workflow, which appears to be ancillary documentation rather than directly addressing the specific request for project-level context guidance. Without visibility into the full extent of these workflow changes, it is unclear whether they are necessary supporting documentation or represent scope creep beyond the stated objective. Please clarify whether the extensions to the "Create Your First Change" section are necessary to support the project-level context guidance, or if they represent separate improvements that should be addressed in a separate PR. This will help determine if all changes are properly scoped to the issue's requirements.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check ✅ Passed The pull request title "docs: add guidance for populating project-level context" directly and specifically describes the main objective of the changes. It clearly indicates that the PR adds documentation (guidance) for setting up project-level context, which aligns with the changeset's primary purpose of documenting how to populate project.md with project details, tech stack, and conventions. The title is concise, specific enough that a teammate scanning history would understand the change, and contains no vague or misleading language.
Linked Issues Check ✅ Passed Issue #234 requests documentation on how to set up project-level guidance (such as Non-Negotiable Aspects and Architectural Style) within OpenSpec. The PR directly addresses this by adding a new section with guidance for populating project.md with project details, tech stack, and conventions after running openspec init, along with an example prompt. This provides the requested documentation that was missing from the existing docs, fulfilling the reporter's need to understand how to surface project-level guidance artifacts.
✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1f18aad and 10e1c8a.

📒 Files selected for processing (1)
  • README.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • README.md

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a 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

📥 Commits

Reviewing files that changed from the base of the PR and between fb1d37e and 1f18aad.

📒 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>
Copy link
Contributor

@TabishB TabishB left a 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.
Copy link
Contributor

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Good point. Thanks.

@TabishB TabishB merged commit a665807 into Fission-AI:main Oct 26, 2025
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Question: How do I set guidance at project level. Example: Kiro Steering Docs, Spec Kit Constitution

2 participants