refactor(agents): consolidate metadata layout

[trumpyla]

Description

Related to issue #26: Refactor agent metadata layout

Type of Change

• 🐛 Bug fix (fix)
• ✨ New feature (feat)
• 💥 Breaking change (feat! or fix!)
• 📝 Documentation update (docs)
• 🎨 Code style/formatting (style)
• ♻️ Refactoring (refactor)
• ⚡ Performance improvement (perf)
• ✅ Test update (test)
• 🔧 Build/CI update (build/ci)
• 🧹 Chore/maintenance (chore)

Linked Issues

Closes #26

Changes Made

Testing

• Ran existing tests
• Tested locally
• Added new tests

Documentation

• Updated relevant documentation
• Updated README if needed
• Added code comments

Checklist

• Semantic commit messages used
• Branch name follows convention
• All commits reference issue
• CI checks pass
• Self-reviewed code
• No secrets committed

---

🤖 Generated with Claude Code

[github-actions]

Thank you for your contribution! 🎉

Your PR has been validated and is ready for review.

What happens next?

1. Automated checks will run (tests, linting, etc.)
2. Maintainers will review your changes
3. You may be asked to make updates based on feedback
4. Once approved, your PR will be merged

While you wait

• Ensure all CI checks pass ✅
• Review the CONTRIBUTING.md guide
• Check docs/SEMANTIC-COMMITS.md for commit guidelines

---

🤖 This comment was generated automatically

[Copilot]

Pull Request Overview

This PR refactors the agent metadata layout to consolidate configuration management through a centralized manifest system. The changes introduce automated generation of agent configuration files and validation tooling to maintain consistency across Claude and Codex agents.

Key Changes:

• Introduced a JSON manifest (.agents-shared/agent-manifest.json) and Python generator script to produce agent project.md files from shared templates
• Added verification script and integration tests to validate symlink structure and config synchronization
• Restructured agent-specific content by extracting shared guidelines into .agents-shared/project-guidelines.md and introducing .agents-shared/CLAUDE.md for Claude-specific guidance

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/integration/test_agent_layout.sh	New integration test that verifies agent layout structure via the verification script
tests/integration/run_all_tests.sh	Updated to test new automation scripts and run layout verification
scripts/verify_agent_layout.sh	New verification script that validates symlinks, directories, and config synchronization
scripts/agents/generate_agent_configs.py	Python tool to generate agent project.md files from manifest and shared snippets
codex/shared	Removed symlink as part of restructuring
codex/project-context.md	Removed file, content consolidated into shared location
codex/preferences.md	Removed file, content consolidated into shared location
codex	Converted from directory to symlink pointing to .agents-codex
SYMLINKS.md	Updated documentation to reflect new structure and automation
.agents-shared/project-guidelines.md	New shared guidelines file containing agent identity, reminders, and quick reference
.agents-shared/agent-manifest.json	New manifest defining agent configurations and shared content
.agents-shared/CLAUDE.md	New Claude-specific guidance documentation
.agents-codex/project.md	Regenerated from manifest with restructured content
.agents-claude/project.md	Regenerated from manifest with restructured content

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

The return type uses tuple[Mapping[str, Iterable[str]], list[AgentSpec]] which obscures what the first element represents. Consider using a TypedDict or dataclass like SharedConfig to make the return value self-documenting and improve type safety.

[Copilot]

The string concatenation pattern here is fragile and makes it unclear that the output should end with exactly one newline. Consider using a parts list with '\n'.join([front_matter, '', body_text, '']) to make the structure explicit.

Suggested change

	body_text = "\n".join(body_parts).strip()
	content = "\n".join(front_matter_lines).rstrip() + "\n\n" + body_text + "\n"
	body_text = "\n".join(body_parts)
	content = "\n".join([ "\n".join(front_matter_lines), "", body_text, "" ])

[Copilot]

The exit $? is redundant because $? will be 0 if the || exit branch executes (since main already returned non-zero and the || condition was true). This should be main "$@" or use explicit exit codes like main "$@" || exit 1.

Suggested change

	main "$@" || exit $?
	main "$@"