Imported from hemanth-create/AI-agents (AGENTS.md). Install upstream with npx skills add hemanth-create/AI-agents. Copyright stays with the author.

AI-agents Workflow Guide

This repo is a private cross-agent MCP workflow platform. Use it to run the same issue-to-PR workflow through shared Python MCP servers instead of agent-specific business logic.

Server Roles

• project-brain: read-only repo context. Start with search, then use fetch for the exact document you need. Use lookup_ownership, find_related_tests, suggest_edits, assess_change_risk, summarize_conventions, and get_command_guidance when the task needs stronger engineering guidance.
• policy-hub: read-only repo profile and workflow policy. Check this before relying on local command or approval assumptions.
• github-workflow: GitHub issue and PR state. Read tools are safe by default. Write tools are approval-gated and should only run after the intended mutation is clear.
• run-journal: local workflow memory. Create one run per meaningful task, checkpoint major milestones, resume by run_id, and compare outcomes.
• ai_agents_lab init: bootstrap .env, .ai-agents/profile.toml, and .ai-agents/policy.toml for the repo.
• ai_agents_lab run and resume: local v5 workflow runner entrypoints that turn issue context, git state, and local checks into a journal-backed PR draft.
• ai_agents_lab dashboard, console, eval, eval-compare, review-summary, pr-readiness, and pr-closeout: operator surfaces for replay, comparison, live inspection, feedback handling, and merge gating.

Expected Workflow

1. Read the issue with github-workflow.get_issue.
2. Pull discussion context with list_issue_comments when the issue is ambiguous.
3. Search project-brain for architecture, workflow, ownership, config, code, test, or workspace context.
4. Read policy-hub before assuming allowed commands, branch defaults, reviewer behavior, or closeout rules.
5. Start or reuse a shared journal run and checkpoint material workflow milestones.
6. Make the local code or docs change outside MCP, run checks locally, and record the outcome in the journal.
7. Use ai_agents_lab run for a fresh run or ai_agents_lab resume when continuing from an existing run_id.
8. Inspect review state and CI with list_pr_files, list_pr_reviews, list_review_comments, summarize_pr_feedback, list_check_runs_for_ref, and get_combined_status.
9. Reply to inline feedback before merge when summarize_pr_feedback shows open threads.
10. Use GitHub write tools only after explicit approval.
11. Use dashboard or console when the operator needs live visibility into blockers, comparisons, or draft outputs.

Success Criteria

• No agent-specific changes are required in the MCP servers.
• GitHub write tools are treated as approval-gated mutations.
• A run summary and checkpoint trail exist before a draft PR or issue update is prepared.
• project-brain and policy-hub remain the source of truth for repo workflow rules.
• The v5 runner uses the repo-local .venv by default when one exists and stores repo-state artifacts for replay and resume.