misc: Add workflow guides and an ExecPlan example

[jensen-yan]

Motivation

This PR formalizes part of our internal collaboration workflow inside the repository instead of keeping it implicit in repeated chat guidance.

The goal is to make agent-assisted and human-driven work more consistent by documenting:

• when complex tasks should be tracked with an ExecPlan
• where to start reading the codebase
• what validation is expected for non-trivial changes
• what a completed ExecPlan looks like in practice

What This PR Adds

1. Repository workflow guides

• Add AGENTS.md as a repository-level collaboration guide
• Add PLANS.md as the ExecPlan writing guide
• Stop ignoring AGENTS.md in .gitignore

These guides cover planning expectations, environment assumptions commonly used on our shared servers, validation rules, and commit / PR conventions.

2. A completed ExecPlan example

• Add docs/exec-plans/completed/phr-rtl-alignment.md

This example records a real investigation of the PHR target-alignment issue from PR #814, including:

• the RTL path-history update semantics
• the consistency check against gem5
• the supporting gcc12-spec06-0.8c performance analysis

Notes

• AGENTS.md and PLANS.md are written in English so they can serve as stable repository-level guides.
• PLANS.md explicitly allows ExecPlans themselves to default to Chinese for internal development efficiency.
• The included completed ExecPlan is intentionally kept in Chinese as an internal-facing example of actual usage.

Impact

This PR does not change simulator behavior.
It only adds repository workflow documentation and one completed example plan.

Summary by CodeRabbit

• Documentation
  • Added repository collaboration guidelines and workflow standards.
  • Added framework for planning and managing complex, multi-step tasks.
  • Added project verification documentation for technical alignment work.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 808127ee-7ccf-477c-a377-35a45341504a

📥 Commits

Reviewing files that changed from the base of the PR and between abf85ff and 2b74a88.

📒 Files selected for processing (4)

• .gitignore
• AGENTS.md
• PLANS.md
• docs/exec-plans/completed/phr-rtl-alignment.md

💤 Files with no reviewable changes (1)

• .gitignore

---

📝 Walkthrough

Walkthrough

The changes introduce repository documentation and collaboration guidelines. Three new documentation files are added: AGENTS.md for collaboration standards and workflow expectations, PLANS.md for the "ExecPlan" process for complex multi-step tasks, and a completion report documenting PHR-RTL alignment verification. The .gitignore is updated to track AGENTS.md.

Changes

Cohort / File(s)	Summary
Meta Configuration .gitignore	Removed AGENTS.md from ignore list to enable tracking of the new collaboration guidelines file.
Repository Guidelines AGENTS.md	Added collaboration and workflow guidelines including repository structure map, environment assumptions, standard build/run/test entry points, style conventions, and validation/commit/PR expectations.
Planning Documentation PLANS.md	Added "ExecPlan" process documentation defining structure for planning complex multi-step tasks, including template, recommended directory organization, writing principles, and required sections (title, background, hypotheses, planned steps, validation, progress tracking).
Completed Plans docs/exec-plans/completed/phr-rtl-alignment.md	Added completion report documenting gem5 and XiangShan RTL alignment on PHR (path history register) semantics, including technical analysis, validation process, performance metrics, and completion checklist.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• misc: add phr design docs[skip ci] #813: Related PHR documentation effort documenting path history register design and semantics across multiple execution plans.

Poem

🐰 A warren of docs, now neatly arranged,
Plans and agents, aligned and exchanged,
Guidelines mapped, from root to the test,
Complex tasks tamed—let collaboration rest! ✨📋

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'misc: Add workflow guides and an ExecPlan example' accurately summarizes the main change: introducing repository documentation for workflow collaboration (AGENTS.md, PLANS.md) and providing a completed ExecPlan example. It is concise, clear, and directly reflects the primary additions in the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-agents

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

🚀 Coremark Smoke Test Results

Branch	IPC	Change
Base (xs-dev)	2.2709	-
This PR	2.2709	➡️ 0.0000 (0.00%)

✅ Difftest smoke test passed!