docs(pr-specs): add agent capabilities and reorganize PR execution plan

[raychrisgdp]

Summary

Issues & Goals:

• Improve clarity and organization of PR specifications to guide implementation work
• Add missing PR specifications for agent tool-calling, event system, multi-agent orchestration, and observability
• Reorganize PR execution plan to reflect improved dependency structure and execution strategy
• Consolidate existing PR specs by reducing verbosity while maintaining essential information

Implementation Highlights:

• Added 6 new PR specifications: PR-003B-agent-tool-calling.md (tool-calling foundation), PR-013-event-system.md (event system + realtime updates), PR-014-multi-agent-orchestration.md (multi-agent orchestration), PR-015-agent-ux-panel.md (agent UX panel), PR-016-observability-baseline.md (structured logging + telemetry), PR-017-db-config-followups.md (DB config follow-ups)
• Refactored existing PR specs: Streamlined PR-001 through PR-012 by reducing verbosity while preserving essential scope, acceptance criteria, and test scenarios
• Updated PR execution plan: Reorganized docs/02-implementation/PR-PLANS.md with new execution order prioritizing observability early and agent capabilities after chat foundation
• Updated PR specs index: Added new PR specs to docs/02-implementation/pr-specs/INDEX.md for discoverability
• Minor documentation fixes: Fixed whitespace formatting in docs/02-implementation/AGENT_GUIDE.md

How to Test

Documentation Review & Validation:

Since this PR contains only documentation changes, reviewers should focus on:

1. PR Specification Completeness:

   • Review each new PR spec (PR-003B, PR-013, PR-014, PR-015, PR-016, PR-017) to ensure:
     • Goals and user value are clearly stated
     • Scope (In/Out) is well-defined
     • Technical design sections are complete
     • Dependencies are correctly identified
     • Test scenarios are actionable

2. PR Execution Plan Validation:

   • Review docs/02-implementation/PR-PLANS.md to verify:
     • Execution order makes sense (observability early, agent capabilities after chat)
     • Dependency graph is accurate (check the mermaid diagram)
     • Skill enrichment tags align with implementation needs
     • No circular dependencies exist

3. Cross-Reference Consistency:

   • Verify that PR specs reference correct design documents in docs/01-design/
   • Check that INDEX.md entries match actual PR spec files
   • Ensure dependency chains are consistent across specs

4. Specification Quality:

   • Review refactored PR specs (PR-001 through PR-012) to ensure:
     • Essential information is preserved
     • Verbosity reduction doesn't remove critical details
     • Test scenarios remain actionable
     • Scope boundaries are still clear

5. Template Consistency:

   • Verify that new PR specs follow the template structure in docs/02-implementation/pr-specs/TEMPLATE.md
   • Check that section ordering and formatting are consistent

Manual Review Steps:

1. Read new PR specs: Start with PR-003B-agent-tool-calling.md, PR-013-event-system.md, and PR-014-multi-agent-orchestration.md to understand the new capabilities being planned
2. Review execution plan: Read PR-PLANS.md to understand how the new PRs fit into the overall strategy
3. Check dependencies: Verify that dependency chains make sense (e.g., PR-003B depends on PR-003, PR-013 depends on PR-002 and PR-004)
4. Validate refactored specs: Spot-check a few refactored PR specs (e.g., PR-001-db-config.md, PR-002-task-crud-api.md) to ensure essential information is preserved
5. Verify index: Check that INDEX.md accurately lists all PR specs

Expected Behavior:

• All PR specs should be self-contained and actionable
• Execution plan should show a logical progression from foundation → observability → UX → chat → agents → features
• Dependency graph should be acyclic and reflect actual technical dependencies
• Cross-references should point to existing design documents
• No broken links or missing files

Related Issues

• None

Author Checklist

• Synced with latest main branch
• Self-reviewed
• All tests pass locally
• Documentation updated (if applicable)
• No breaking changes (or documented if intentional)

Additional Notes

Key Implementation Areas for Review

New PR Specifications:

• docs/02-implementation/pr-specs/PR-003B-agent-tool-calling.md: Tool-calling foundation for safe agent actions - verify scope boundaries and security considerations
• docs/02-implementation/pr-specs/PR-013-event-system.md: Event system for realtime updates - verify SSE endpoint design and webhook delivery approach
• docs/02-implementation/pr-specs/PR-014-multi-agent-orchestration.md: Multi-agent orchestration - verify architectural pattern selection (Swarm vs Supervisor) and shared memory design
• docs/02-implementation/pr-specs/PR-015-agent-ux-panel.md: Agent UX panel for TUI - verify integration with PR-008 (TUI) and PR-014 (orchestration)
• docs/02-implementation/pr-specs/PR-016-observability-baseline.md: Observability baseline - verify early placement in execution order and integration points
• docs/02-implementation/pr-specs/PR-017-db-config-followups.md: DB config follow-ups - verify these address gaps from PR-001

PR Execution Plan:

• docs/02-implementation/PR-PLANS.md: Major reorganization - verify new execution order prioritizes observability early and agent capabilities after chat foundation. Check that dependency graph accurately reflects technical dependencies.

Refactored PR Specs:

• All existing PR specs (PR-001 through PR-012) were streamlined - verify essential information (scope, acceptance criteria, test scenarios) is preserved while verbosity is reduced.

Testing Notes

• Worktree state: One untracked file (reviews/REVIEW_c-improve-pr-based-on-skills.md) exists but doesn't affect this PR
• Documentation-only PR: No code changes, so no automated tests to run. Focus on manual documentation review and consistency checks.
• Cross-reference validation: Reviewers should verify that all references to design documents (docs/01-design/*.md) are valid and that dependency chains are consistent.