chore: add agent-readiness governance templates#7
Conversation
PRD.md: full epic/story/acceptance-criteria breakdown for all 8 profiler subcommands (system metrics, network, disk, audit, complexity, continuous monitoring, chart generation, instrumented builds). FUNCTIONAL_REQUIREMENTS.md: 18 FR-XXX-NNN SHALL statements with PRD traces replacing generic placeholder content. ADR.md: 6 architecture decisions covering Bash/Python dispatch split, timestamped report files, ast-based complexity analysis, CSV wire format, matplotlib-only charts, and pgrep PID resolution. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add bin/system_metrics.py: CPU%, memory used/total, swap, disk usage per mountpoint, and network I/O counters collected via psutil - Exports structured JSON snapshot to stdout or --output file - --watch N flag for continuous polling every N seconds - --pretty flag for human-readable indented JSON - wraps: psutil (latest stable) - Verified: produces correct JSON on macOS with psutil 6.x Co-authored-by: Claude Code <claude@anthropic.com>
- Moved all kitty-specs features to docs/specs/<feature>/ - Added meta.json with migrated status for features missing it - Archived original kitty-specs/ to .archive/kitty-specs/ - Updated .gitignore to allow docs/specs tracking if needed Co-authored-by: Claude Code <claude@anthropic.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
- Add CODEOWNERS with @KooshaPari as sponsor - Add AGENTS.md extending phenotype-governance - Add issue/PR templates for task discovery - Add linter configs where applicable - Add CI workflow for automated quality gates
Added: - SECURITY.md - security policy - TEST_COVERAGE_MATRIX.md - test coverage tracking Stabilization complete
|
Warning You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again! |
|
You have used all Bugbot PR reviews included in your free trial for your GitHub account on this workspace. To continue using Bugbot reviews, enable Bugbot for your team in the Cursor dashboard. |
|
Your free trial PR review limit of 100 PRs has been reached. Please upgrade your plan to continue using CodeAnt AI. |
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 16 minutes and 28 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (35)
✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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 |
|
You are seeing this message because GitHub Code Scanning has recently been set up for this repository, or this pull request contains the workflow file for the Code Scanning tool. What Enabling Code Scanning Means:
For more information about GitHub Code Scanning, check out the documentation. |
There was a problem hiding this comment.
Pull request overview
This PR introduces “agent-readiness” governance scaffolding (templates, CI/workflows, coverage, changelog tooling) and also adds/updates a substantial set of product & documentation artifacts for the Profila/profiler project.
Changes:
- Added GitHub issue/PR templates plus multiple CI workflows (CI, quality gate, coverage, security, release, benchmarks).
- Added repository governance/config files (Codecov, pre-commit, EditorConfig, mise tasks, git-cliff config).
- Added/expanded documentation and planning artifacts (PRD/FRs/ADR, VitePress docs) and introduced
bin/system_metrics.py.
Reviewed changes
Copilot reviewed 34 out of 35 changed files in this pull request and generated 22 comments.
Show a summary per file
| File | Description |
|---|---|
| TEST_COVERAGE_MATRIX.md | Adds a coverage-mapping template document. |
| SECURITY.md | Adds a security policy and reporting instructions. |
| PRD.md | Expands PRD content and epics/acceptance criteria. |
| mise.toml | Adds mise task automation for format/lint/test/build/audit/docs. |
| FUNCTIONAL_REQUIREMENTS.md | Replaces placeholder FRs with detailed traced requirements. |
| docs/traceability/index.md | Adds traceability docs page content (includes custom component markup). |
| docs/stories/index.md | Adds user stories index page. |
| docs/stories/hello-world.md | Adds a “Hello World” story (Rust-oriented example). |
| docs/specs/001-profiler/spec.md | Adds spec document. |
| docs/specs/001-profiler/plan.md | Adds plan document. |
| docs/specs/001-profiler/meta.json | Adds spec metadata. |
| docs/journeys/quick-start.md | Adds “Quick Start” journey (includes custom component markup). |
| docs/journeys/index.md | Adds journeys index page. |
| docs/AGENT_READINESS_AUDIT.md | Adds an agent-readiness audit report. |
| docs/.vitepress/config.mts | Adds an additional VitePress config file. |
| CONTRIBUTING.md | Adds contributor guide. |
| codecov.yml | Adds Codecov thresholds and ignore rules. |
| cliff.toml | Adds git-cliff changelog configuration. |
| bin/system_metrics.py | Adds a psutil-based system metrics collector script. |
| ADR.md | Adds architecture decision records. |
| .pre-commit-config.yaml | Adds pre-commit hooks including trufflehog. |
| .github/workflows/security.yml | Adds security scanning workflows (pip-audit/safety/semgrep/trivy/gitleaks). |
| .github/workflows/release.yml | Adds release workflow for tagging, publishing, and GitHub releases. |
| .github/workflows/quality-gate.yml | Adds lint/format/type/test/bandit quality gate workflow. |
| .github/workflows/coverage.yml | Adds a coverage workflow stub with Codecov upload. |
| .github/workflows/ci.yml | Adds CI workflow for lint/type/test/coverage upload. |
| .github/workflows/benchmark.yml | Adds benchmark workflow and a main-branch comparison job. |
| .github/pull_request_template.md | Adds PR template checklist. |
| .github/ISSUE_TEMPLATE/feature.yml | Adds Issue Forms feature request template. |
| .github/ISSUE_TEMPLATE/feature_request.md | Adds legacy markdown feature request template. |
| .github/ISSUE_TEMPLATE/bug.yml | Adds Issue Forms bug report template. |
| .github/ISSUE_TEMPLATE/bug_report.md | Adds legacy markdown bug report template. |
| .editorconfig | Adds EditorConfig settings for formatting consistency. |
| .archive/kitty-specs/001-profiler/spec.md | Adds archived spec copy. |
| .archive/kitty-specs/001-profiler/plan.md | Adds archived plan copy. |
| - "**/tests/**" | ||
| - "**/test/**" | ||
| - "**/*.py" |
There was a problem hiding this comment.
ignore includes "**/*.py", which will exclude essentially all Python source files from coverage calculation and make Codecov status checks meaningless. Remove that pattern (and scope ignores to generated/build artifacts only) so project/patch coverage reflect actual code changes.
| - "**/tests/**" | |
| - "**/test/**" | |
| - "**/*.py" |
| range: "70...100" | ||
| status: | ||
| project: | ||
| default: | ||
| target: 80% | ||
| threshold: 5% | ||
| patch: | ||
| default: | ||
| target: 80% | ||
| threshold: 5% |
There was a problem hiding this comment.
PR description mentions a 70% project minimum, but coverage.status.project.default.target is set to 80%. Either update the config to match the stated policy or adjust the PR description/policy so they stay consistent.
| - name: Run coverage | ||
| run: | | ||
| # Language-specific coverage commands | ||
| echo "Coverage check configured" | ||
| - name: Upload coverage | ||
| uses: codecov/codecov-action@v4 |
There was a problem hiding this comment.
This workflow never runs tests or generates a coverage report (it only echoes a message), so the subsequent Codecov upload will either fail or report no coverage. Replace the placeholder with the repo’s real test/coverage command(s) and ensure an artifact like coverage.xml is produced before uploading.
| - name: Run coverage | |
| run: | | |
| # Language-specific coverage commands | |
| echo "Coverage check configured" | |
| - name: Upload coverage | |
| uses: codecov/codecov-action@v4 | |
| - name: Set up Node.js | |
| if: ${{ hashFiles('package.json') != '' }} | |
| uses: actions/setup-node@v4 | |
| with: | |
| node-version: '20' | |
| cache: npm | |
| - name: Set up Python | |
| if: ${{ hashFiles('pyproject.toml') != '' || hashFiles('requirements.txt') != '' || hashFiles('setup.py') != '' }} | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.x' | |
| - name: Run coverage | |
| shell: bash | |
| run: | | |
| set -euo pipefail | |
| if [ -f package.json ]; then | |
| npm ci | |
| npm run coverage --if-present | |
| if [ ! -f coverage.xml ] && [ ! -f coverage/lcov.info ]; then | |
| npm test -- --coverage | |
| fi | |
| elif [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then | |
| python -m pip install --upgrade pip | |
| if [ -f requirements.txt ]; then | |
| python -m pip install -r requirements.txt | |
| fi | |
| python -m pip install pytest pytest-cov | |
| python -m pytest --cov --cov-report=xml:coverage.xml | |
| else | |
| echo "No supported coverage command is configured for this repository." | |
| exit 1 | |
| fi | |
| if [ -f coverage.xml ]; then | |
| echo "COVERAGE_FILE=coverage.xml" >> "$GITHUB_ENV" | |
| elif [ -f coverage/lcov.info ]; then | |
| echo "COVERAGE_FILE=coverage/lcov.info" >> "$GITHUB_ENV" | |
| else | |
| echo "Coverage report was not generated." | |
| exit 1 | |
| fi | |
| - name: Upload coverage | |
| uses: codecov/codecov-action@v4 | |
| with: | |
| files: ${{ env.COVERAGE_FILE }} |
| run: mypy src/ | ||
|
|
||
| - name: Run tests | ||
| run: pytest --cov=src --cov-report=xml |
There was a problem hiding this comment.
The workflow lints/types/tests src/, but this repository doesn’t have a top-level src/ directory. As written, mypy src/ and pytest --cov=src will fail. Update paths to the actual code locations (e.g., bin/ for Python scripts) or add the expected package layout before enabling these checks.
| run: mypy src/ | |
| - name: Run tests | |
| run: pytest --cov=src --cov-report=xml | |
| run: mypy . | |
| - name: Run tests | |
| run: pytest --cov=. --cov-report=xml |
| env: | ||
| CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} | ||
|
|
||
| - name: Upload coverage | ||
| uses: codecov/codecov-action@v4 | ||
| with: |
There was a problem hiding this comment.
CODECOV_TOKEN is exported into the test process environment, but tests don’t need it to generate coverage.xml and it increases the risk of accidental leakage via logs. Prefer passing the token only to codecov/codecov-action (and omit it entirely for public repos).
| env: | |
| CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }} | |
| - name: Upload coverage | |
| uses: codecov/codecov-action@v4 | |
| with: | |
| - name: Upload coverage | |
| uses: codecov/codecov-action@v4 | |
| with: | |
| token: ${{ secrets.CODECOV_TOKEN }} |
| cd Profila | ||
|
|
||
| # Run profiler | ||
| cd profiler |
There was a problem hiding this comment.
The setup instructions cd profiler assume a profiler/ subdirectory, but this repo’s entrypoint script is at the repository root (./profiler.sh) and there’s no top-level profiler/ directory. Update the paths/commands so a new contributor can follow them verbatim.
| cd profiler |
| ## Quick Wins (Implement Today) | ||
|
|
||
| 1. **Copy gitleaks.toml** from `/Users/kooshapari/CodeProjects/Phenotype/repos/gitleaks.toml` | ||
| 2. **Expand pre-commit** with ruff-pre-commit hooks | ||
| 3. **Create tests directory** with basic pytest structure | ||
| 4. **Add PR template** with checklist | ||
| 5. **Expand CODEOWNERS** with specific file ownership | ||
| 6. **Create codecov.yml** with 80% patch coverage target | ||
|
|
||
| --- | ||
|
|
||
| ## Reference Patterns | ||
|
|
||
| | Pattern | Source | File | | ||
| |---------|--------|------| | ||
| | Pre-commit config | phenotype-infrakit | `phenotype-infrakit/.pre-commit-config.yaml` | | ||
| | gitleaks rules | repos root | `/Users/kooshapari/CodeProjects/Phenotype/repos/gitleaks.toml` | | ||
| | codecov config | phenotype-infrakit | `phenotype-infrakit/codecov.yml` | | ||
| | Taskfile patterns | Tokn | `Tokn/Taskfile.yml` | |
There was a problem hiding this comment.
This document includes machine-specific absolute paths (e.g., /Users/kooshapari/...) in the “Quick Wins” / reference sections, which won’t be actionable for other contributors and can leak local environment details. Replace with repo-relative paths or links to the canonical source location.
| [*.{py,pyi}] | ||
| indent_style = space | ||
| indent_size = 4 | ||
| max_line_length = 120 |
There was a problem hiding this comment.
.editorconfig sets max_line_length = 120 for Python, but AGENTS.md documents a 100-character line-length constraint (AGENTS.md:238-242) and mise.toml runs Black with --line-length 100. Align these to a single value to avoid formatter/linter conflicts.
| max_line_length = 120 | |
| max_line_length = 100 |
| [tasks.docs:build] | ||
| description = "Build documentation" | ||
|
|
||
| run = "sphinx-build -b html docs docs/_build" | ||
|
|
There was a problem hiding this comment.
docs:build runs sphinx-build, but this repo’s docs/ uses VitePress (docs/package.json has vitepress build) and there’s no Sphinx config. Update the task to call the actual docs build command so mise run docs:build works.
| # Product Requirements Document — profiler | ||
|
|
||
| **Status:** ACTIVE | ||
| **Owner:** Phenotype Engineering | ||
| **Last Updated:** 2026-03-26 | ||
|
|
||
| --- | ||
|
|
||
| ## Overview | ||
|
|
||
| This document defines the product requirements, epics, and user stories for **profiler**. | ||
| `profiler` is a unified shell-and-Python profiling toolkit for the Phenotype agent ecosystem. It collects system-level resource metrics (memory, CPU, network, disk I/O), measures code complexity, generates machine-readable CSV output, and produces visual charts — all from a single entry-point script targeting a named process or codebase. | ||
|
|
||
| ## Project Description | ||
| Primary consumers: agent performance audits on `codex`, `thegent`, `heliosCLI`, and similar Phenotype processes running on macOS/Linux developer machines and CI runners. | ||
|
|
||
| Comprehensive profiling and benchmarking system for analyzing agent and system performance. | ||
| --- |
There was a problem hiding this comment.
The PR title/description focuses on adding governance templates (issue/PR templates, Codecov config, mise/cliff), but the diff also adds substantial product/documentation content (PRD/ADR updates, VitePress docs, new bin/system_metrics.py). If these are intentional, the PR description should be expanded to reflect the broader scope; otherwise consider splitting into separate PRs for governance vs. product/docs changes.
Add standardized governance files for improved agent-readiness compliance:
Generated by pheno-cli bootstrap. Improves Task Discovery, Security, and Style & Validation compliance categories.