Align documentation with code implementation

[Copilot]

Documentation contained multiple inaccuracies about feature availability and behavior. This PR corrects those discrepancies.

Changes

Clarified feature availability

• Agent-based filtering: Documented as not implemented (code has ShouldExcludePath method but never calls it)
• Parent directory traversal: Removed references - search only covers directories specified via -d, working dir, and home dir
• Parameter substitution: Corrected from bash-style ${var:-default} syntax to simple ${var} lookup (unresolved params remain unchanged)

Fixed terminology

• .agents/commands: Changed from "(tasks)" to "(reusable content blocks)" - commands are referenced via slash syntax within tasks, not invoked directly
• Task matching: Clarified "Multiple Tasks with Same task_name" → "Multiple Tasks with Same Filename" - tasks match by filename, not frontmatter field

Corrected output format

• Task frontmatter: Added missing documentation that frontmatter is always output first in YAML format

Files updated

• README.md - agent flag, commands terminology, parent directory references
• SLIDES.md - agent flag description
• docs/explanation/architecture.md - search paths, parameter syntax, output format
• docs/reference/file-formats.md - task matching behavior

Original prompt

Please thoroughly review the code and docs and make sure the docs match the code.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR corrects documentation inaccuracies to align with the actual code implementation, focusing on feature availability, behavior descriptions, and terminology.

Key Changes

• Clarified that agent-based path filtering is not implemented (ShouldExcludePath method exists but is never called)
• Corrected search path documentation to reflect actual behavior (directories via -d, working dir, and home dir only - no parent directory traversal)
• Updated parameter substitution documentation to match simple ${var} behavior (unresolved parameters remain unchanged)
• Fixed task matching terminology to correctly state that matching is by filename, not by task_name frontmatter field
• Clarified -a flag purpose (required for -w flag) rather than incorrectly describing it as excluding agent paths
• Corrected ".agents/commands" description from "(tasks)" to "(reusable content blocks)"
• Added missing documentation that task frontmatter is output first in YAML format

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
docs/reference/file-formats.md	Updated task matching section to clarify filename-based matching and corrected error message text
docs/explanation/architecture.md	Corrected search path list, parameter substitution syntax, and output assembly order
SLIDES.md	Updated -a flag description to reflect actual purpose (for -w flag)
README.md	Corrected commands terminology, removed parent directory references, updated -a flag description

Comments suppressed due to low confidence (1)

docs/reference/file-formats.md:811

• The documentation states that with selectors, if multiple tasks match, an error is produced. However, the code does not validate uniqueness. Looking at the task finding logic in context.go, files that pass selector matching (line 91) are processed by the visitor, and if multiple tasks match both the filename and selectors, the last one found will be used without any error. The same issue exists: the last matching task silently wins.

**With selectors:**
- The task matching all selectors is used
- If no task matches: "no task found"
- If multiple match: Error

[Copilot]

The documentation states that an error "multiple tasks found with name: X" is produced when multiple task files have the same filename without selectors. However, the code never produces this error. Looking at the task finding logic in context.go lines 105-210, when multiple files match, the visitor function processes each match and the last one found overwrites the previous one (cc.task is assigned on line 192). No duplicate detection or error is raised. The actual behavior is: the last matching task file wins, silently.