docs: comprehensive file-formats documentation with inline examples

[rudironsoni]

Summary

This PR adds comprehensive documentation for Rulesync file formats.

Changes

File	Description
docs/reference/file-formats.md	Main documentation covering all Rulesync configuration formats
skills/rulesync/file-formats.md	Skill definition for file-formats documentation

Documentation Coverage

• Complete reference for all Rulesync configuration file formats
• Version-annotated inline examples for every supported format
• Detailed field descriptions with types, defaults, and usage

Checklist

• Documentation follows project formatting standards (oxfmt)
• No generated files committed
• No unrelated changes included
• Single commit with clean history

[dyoshikawa-claw]

/opencode review

[Copilot]

Pull request overview

This PR substantially expands the Rulesync “File Formats” documentation, adding detailed, version-annotated field references and comprehensive inline examples across all supported configuration formats.

Changes:

• Expanded file-format docs with comprehensive YAML/JSON examples and per-field version notes.
• Added hook event support tables/mappings and an expanded “Supported Tools” + version reference section.
• Mirrored the same reference content into the Rulesync skill documentation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 13 comments.

File	Description
skills/rulesync/file-formats.md	Mirrors the file-formats reference inside the Rulesync skill docs, including examples, hook docs, supported-tools table, and version history.
docs/reference/file-formats.md	Adds the primary comprehensive file-formats reference under docs/reference with detailed examples, event mapping tables, supported tools, and version reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This “Comprehensive Example” is fenced as json but contains // comments, which makes it invalid JSON and not directly copy/pasteable into .rulesync/hooks.json. Consider switching the fence to jsonc (and/or explicitly labeling it as “annotated”) and/or provide a separate valid JSON example without comments.

[Copilot]

This version list labels v7.10.1 as “Current”, but the repository’s package version is 7.10.0. Please either update this to reflect the current released version or clarify that v7.10.1 is unreleased/planned.

Suggested change

	### v7.10.1 (Current)
	- Patch release with minor fixes
	- Dependency updates
	### v7.10.1 (Planned)
	- Planned patch release with minor fixes
	- Planned dependency updates

[github-actions]

PR #1223 Review Results

Code Review Findings

Critical Issues:

1. Invalid YAML Syntax in Examples - YAML frontmatter examples use invalid syntax where values appear on separate lines from keys (e.g., root: followed by newline and true). This creates invalid nested structures. All YAML examples need syntax correction throughout both documentation files.

2. Significant Content Discrepancy Between Documentation Files - The two modified files have different change volumes (~160 line difference), suggesting they may not be synchronized. Since skills/ is distributed to users and docs/ is the main reference, consistency is critical.

Medium Issues:

3. Version History Has Placeholder Content - Version history (v5.1.0 - v6.9.x) contains generic placeholder text ("Various bug fixes and improvements") that's not useful for users. Should provide actual release notes or link to CHANGELOG.md.

4. Incomplete Feature Matrix - The "Complete Feature Matrix by Version" jumps from v5.0.0 to v7.6.0, skipping v6.x versions entirely, inconsistent with the Version Reference section.

5. Inconsistent Event Mapping Tables - Event mapping tables show support indicators that don't match the actual mappings (e.g., OpenCode stop → session.idle but table shows different mapping).

6. Missing Section Header - Version history section lacks proper header, appearing abruptly after "Conflicting Targets" section.

Minor Issues:

7. cspell.json Addition - Adding "worktree" to cspell.json is tangentially related to documentation but affects spell-checking configuration.

8. dryRun vs check Confusion - Both options appear to validate without writing but their distinction is unclear in documentation.

Positive Observations:

9. Documentation Follows Standards - Documentation follows oxfmt formatting standards per PR description.

10. Well-Structured Examples - New "Comprehensive Example" format with version-annotated inline comments is a significant improvement over previous minimal examples.

Security Review Findings

Overall Assessment: ✅ LOW RISK - No Critical Security Issues Found

Good Security Practices:

11. Placeholder Credentials - Documentation uses appropriate placeholders ("Bearer token", "secret") for sensitive fields.

12. Security Note for Trust Field - Includes appropriate security warning about trusting servers from verified sources.

13. Localhost URLs - All URL examples use localhost, preventing accidental exposure to external services.

14. Removed External Package Reference - Replaced reference to real external package (git+https://github.com/oraios/serena) with placeholder, reducing risk.

15. No Path Traversal Patterns - File paths use safe relative references without ../ patterns.

16. Proper Ignore File Guidance - Documentation correctly recommends ignoring sensitive files in .aiignore (.env, credentials/, *.key, etc.).

Minor Security Recommendations:

17. Hook Command Security - Consider adding explicit warning about security implications of running arbitrary shell commands from hooks.

18. External Sources Warning - Add guidance about verifying external skill sources before fetching.

19. MCP Configuration Security - Consider adding general security section for MCP server configuration (command execution, environment variables, auto-approve settings).

20. Environment Variable Injection - Document that environment variables should be validated if they come from untrusted sources.

21. Auto-Approve Settings - Add warnings about security implications of alwaysAllow, kiroAutoApprove, and similar bypass features.

Verdict

Overall Assessment: Needs Revision

The PR significantly improves documentation coverage with well-structured examples. However, the critical YAML syntax issues (Finding #1) and content discrepancy between files (Finding #2) must be addressed before merging. From a security perspective, the PR is safe to merge with only minor recommendations for improvement.

github run

[cm-dyoshikawa]

@rudironsoni Thank you. However sorry, I'm going to reject this. If the documentation is too detailed, it will be difficult to maintain as updates are made. I think it would be better to keep the documentation simple and use something like a deepwiki that works with the source code to help people understand how to use it in detail.