Enhance documentation, tooling, and rules consistency#32
Merged
Conversation
- Updated hooks documentation to clarify Copilot and Cursor event mappings and confidence levels. - Revised compatibility matrix to reflect changes in skills, agents, rules, and hooks support across platforms. - Added migration details for converting UAAPS packages to Codex-native structure, including output layout and artifact mapping. - Improved packaging guidelines to ensure deterministic archive builds and proper file selection. - Expanded dependency management to include tooling groups and feature selectors for enhanced package functionality. - Introduced structured source metadata in lock files for better package resolution tracking. - Strengthened validation rules for package manifests, including checks for extras and dependency groups. - Updated security guidelines to emphasize package contents and permissions management. - Created GitHub issue templates for bug reports, feature requests, and tasks to streamline issue tracking. - Added a pre-commit documentation guard agent to ensure changelog and README accuracy before commits.
There was a problem hiding this comment.
Pull request overview
This PR expands the UAAPS specification and supporting tooling/docs to cover richer rule semantics (UARS), dependency “groups” and consumer “extras”, lockfile v2 structured source metadata, and adds several agent/skill assets intended for common workflows (docs guard, CI triage, PR comment handling, issues, governance/eval).
Changes:
- Extend spec chapters (rules, dependencies, packaging, security/validation, compatibility/migration) to formalize dependency groups + extras, packlist determinism, and effective-permission semantics.
- Update JSON schemas for rule frontmatter, package manifest, and lockfile (v2) to match the expanded spec.
- Add new agent/skill artifacts and helper scripts/assets (GitHub issue mgmt, PR checks inspection, comment fetching, pre-commit docs guard), plus changelog/version/readme updates.
Reviewed changes
Copilot reviewed 39 out of 44 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/spec/16-security.md | Adds guidance for extra-selected permissions and updates “root authority” semantics. |
| docs/spec/15-validation.md | Adds new validation rules for lock v2 source metadata, files, groups/extras, and effective-permission auditing. |
| docs/spec/12-dependencies.md | Defines dependency groups/extras semantics, lockfile v2 source object, and install flags/syntax. |
| docs/spec/11-packaging.md | Specifies deterministic packlist selection + reproducible archive build and strengthens immutability rules. |
| docs/spec/10-migration.md | Updates platform install targets and adds a Codex-native export target mapping. |
| docs/spec/09-compatibility.md | Updates compatibility/confidence matrix and clarifies AGENTS.md behavior for Copilot agent mode. |
| docs/spec/07-hooks.md | Adds confidence caveats for Copilot/Cursor hook event naming. |
| docs/spec/06-rules.md | Replaces stub with full UARS v1.3 spec + compiler/converter behavior. |
| docs/spec/05-agents.md | Updates Codex mapping to “generated skills” layout. |
| docs/spec/04-commands.md | Clarifies Claude Code command invocation and Codex generated-skill mapping. |
| docs/spec/03-skills.md | Annotates inferred fields, updates test CLI examples, and adjusts Copilot support status. |
| docs/spec/02-manifest.md | Adds files, dependencyGroups, and extras manifest fields and rules. |
| docs/spec/01-package-format.md | Updates package layout for command tests and recursive rule grouping. |
| docs/schemas/rule-frontmatter.schema.json | Updates schema to UARS v1.3 (name, apply, agents, refs). |
| docs/schemas/package-manifest.schema.json | Adds schema for files, dependencyGroups, extras; refactors systemDependencies. |
| docs/schemas/package-lock.schema.json | Bumps lock schema to v2 with structured source, groups, and selected extras. |
| docs/changelog.md | Adds 0.8.0-draft entry describing new spec/schema/tooling content. |
| README.md | Updates displayed version/build instructions and fixes spec link path. |
| CHANGELOG.md | Adds 0.8.0-draft entry (top-level changelog). |
| .gitignore | Adds ignores for .aam and .agent-packages/. |
| .github/agents/pre-commit-docs.agent.md | Adds a Copilot agent definition for pre-commit docs checks. |
| .claude/skills/github-issues/references/templates.md | Adds issue body templates. |
| .claude/skills/github-issues/SKILL.md | Adds a GitHub issues management skill (MCP-based). |
| .claude/skills/git-commit/SKILL.md | Adds a conventional-commits oriented git commit skill doc. |
| .claude/skills/gh-fix-ci/scripts/inspect_pr_checks.py | Adds a helper script to analyze failing PR checks and extract log snippets. |
| .claude/skills/gh-fix-ci/assets/github.png | Adds skill icon asset. |
| .claude/skills/gh-fix-ci/assets/github-small.svg | Adds skill icon asset. |
| .claude/skills/gh-fix-ci/agents/openai.yaml | Adds Codex/OpenAI UI metadata for the skill. |
| .claude/skills/gh-fix-ci/SKILL.md | Adds skill instructions for CI triage workflow. |
| .claude/skills/gh-fix-ci/LICENSE.txt | Adds license for the skill bundle. |
| .claude/skills/gh-address-comments/scripts/fetch_comments.py | Adds a script to fetch PR comments/reviews/threads via GitHub GraphQL. |
| .claude/skills/gh-address-comments/assets/github.png | Adds skill icon asset. |
| .claude/skills/gh-address-comments/assets/github-small.svg | Adds skill icon asset. |
| .claude/skills/gh-address-comments/agents/openai.yaml | Adds Codex/OpenAI UI metadata for the skill. |
| .claude/skills/gh-address-comments/SKILL.md | Adds skill instructions for addressing PR review comments. |
| .claude/skills/gh-address-comments/LICENSE.txt | Adds license for the skill bundle. |
| .claude/skills/agentic-eval/SKILL.md | Adds evaluation patterns skill content. |
| .claude/skills/agent-governance/SKILL.md | Adds governance/safety patterns skill content. |
| .claude/agents/openai-expert.agent.md | Adds an OpenAI/Codex artifacts expert agent definition. |
| .claude/agents/cursor-expert.agent.md | Adds a Cursor customization expert agent definition. |
| .claude/agents/copilot-expert.agent.md | Adds a GitHub Copilot customization expert agent definition. |
| .claude/agents/coding-agents-expert.agent.md | Adds a general coding-agents expert/router agent definition. |
| .claude/agents/claude-code-expert.agent.md | Adds a Claude Code artifacts expert agent definition. |
| .aam/aam-lock.yaml | Updates lock metadata tracking for added skills/agents sources. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| @@ -0,0 +1,6 @@ | |||
| interface: | |||
| display_name: "GitHub Address Comments" | |||
| short_description: Address comments in a GitHub PR review" | |||
Comment on lines
+366
to
+377
| def fetch_job_log(job_id: str, repo_root: Path) -> tuple[str, str]: | ||
| repo_slug = fetch_repo_slug(repo_root) | ||
| if not repo_slug: | ||
| return "", "Error: unable to resolve repository name for job logs." | ||
| endpoint = f"/repos/{repo_slug}/actions/jobs/{job_id}/logs" | ||
| returncode, stdout_bytes, stderr = run_gh_command_raw(["api", endpoint], cwd=repo_root) | ||
| if returncode != 0: | ||
| message = (stderr or stdout_bytes.decode(errors="replace")).strip() | ||
| return "", message or "gh api job logs failed" | ||
| if is_zip_payload(stdout_bytes): | ||
| return "", "Job logs returned a zip archive; unable to parse." | ||
| return stdout_bytes.decode(errors="replace"), "" |
| "properties": { | ||
| "lockVersion": { | ||
| "description": "Lock file format version. Currently always 1.", | ||
| "description": "Lock file format version. Current version is 2. Tools SHOULD continue reading version 1 for backward compatibility.", |
Comment on lines
132
to
+136
| Package authors SHOULD remove per-platform `plugin` overrides once the target platform is listed as UAAPS-native in the compatibility matrix (§10). | ||
|
|
||
| ## 11.2 Future Build Target — UAAPS Package → Codex Native Structure | ||
|
|
||
| This section defines the intended conversion model for a future toolchain that exports a UAAPS package into a Codex-native repository layout. |
Comment on lines
+73
to
+76
| - Archive entries MUST use forward-slash paths relative to the package root. | ||
| - Archive entries MUST be sorted lexicographically by path before tar creation. | ||
| - `aam pack` MUST fail if the final packlist omits a file referenced by the manifest, a declared artifact entry, or a configured hook/MCP path. | ||
| - Tools SHOULD warn when the packlist includes likely-secret files such as `.env`, `.env.*`, or credential exports. |
Comment on lines
+299
to
+304
| **Rules**: | ||
| - `files` entries MUST be relative paths using forward slashes. | ||
| - `files` entries MUST NOT resolve outside the package root. | ||
| - `files` entries MUST NOT use negated patterns (`!foo/**`). | ||
| - `aam pack` MUST fail if the computed packlist excludes a file referenced by the manifest or by a declared artifact. | ||
| - If `files` is omitted, tools MUST use the default inclusion algorithm defined in §12.1. |
Comment on lines
+18
to
+21
| | Lock file source metadata | `package.agent.lock` version `2` entries MUST store `source` as an object with required fields for the selected source `type` | | ||
| | Manifest `files` | Entries MUST be relative, use forward slashes, and MUST NOT use negated patterns | | ||
| | Archive completeness | `aam pack` MUST fail if the computed packlist omits a referenced artifact, hook, or MCP file | | ||
| | Dependency groups | `dependencyGroups` keys MUST match `[a-z0-9][a-z0-9-]*` and each group MUST declare at least one of `dependencies` or `systemDependencies` | |
Comment on lines
+373
to
+375
| ```markdown | ||
| <!-- aam:begin — managed by aam rules compile; do not edit this block manually --> | ||
|
|
Comment on lines
+428
to
+431
| #### Idempotency | ||
|
|
||
| Running `aam rules compile` twice with no source changes MUST produce bit-identical output files: | ||
|
|
- Unify `aam pack` → `aam pkg pack` across manifest, packaging, and validation specs - Unify `aam rules compile` → `aam pkg rules compile` in rules spec - Clarify lock schema validates v2 only (v1 backward-compat is a tool requirement, not schema) - Fix heading levels in migration guide (## → ### for nested subsections) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
🤖 Generated with Claude Code