Add first-class llms.txt support for AI-native repositories

[coisa]

Problem

DevTools already ships packaged skills, packaged project-agent prompts, and an AGENTS.md authoring skill, which makes the repository increasingly AI-native. A missing piece in that surface is first-class support for llms.txt generation and maintenance.

The need is clear, but there are at least two viable implementation paths:

1. reuse or adapt the documentation-generation stack to emit llms.txt from existing docs metadata;
2. add a dedicated skill and repository workflow for authoring or refreshing llms.txt directly.

The repository should decide this intentionally instead of drifting into an incidental implementation.

Proposal

Add first-class llms.txt support to DevTools, and explicitly evaluate whether the better fit is a template-driven generation path, a dedicated skill-driven authoring workflow, or a hybrid design.

Goals

• Give Fast Forward repositories an endorsed path for generating and maintaining llms.txt.
• Keep the result aligned with the repository's existing documentation, skills, and agent surfaces.
• Avoid duplicating large amounts of canonical content across docs and AI-facing files.

Expected Behavior

A maintainer should be able to adopt llms.txt support in the same product family as AGENTS.md, packaged skills, and synchronized consumer defaults, with a clear recommendation on how the file is produced and refreshed.

Implementation Strategy

1. Evaluate template-driven generation from existing documentation metadata versus a dedicated authoring skill.
2. Choose the model that best preserves canonical sources and minimizes duplication.
3. Implement the selected path with clear update triggers and repository documentation.
4. If needed, keep the architecture open for a second mode later, but avoid shipping both paths prematurely without a clear primary workflow.

Scope

• Product decision for how DevTools should support llms.txt.
• Initial implementation of the chosen path.
• Documentation describing how maintainers create and refresh the file.

Non-goals

• Do not commit to supporting every possible llms.txt dialect in the first version.
• Do not duplicate the entire documentation site into a generated text artifact.
• Do not introduce a second implementation path unless the first one proves insufficient.

Acceptance Criteria

Functional Criteria

• The repository defines an endorsed approach for llms.txt support.
• The chosen implementation can create or refresh llms.txt from repository context.
• The workflow identifies canonical sources and avoids unnecessary duplication.
• Focused tests or deterministic fixture validation cover the generated or maintained output where appropriate.
• README and docs explain how llms.txt support is used and maintained.

Architectural / Isolation Criteria

• MUST: The core logic MUST be isolated into dedicated classes or services instead of living inside command or controller entrypoints.
• MUST: Responsibilities MUST be separated across input resolution, domain logic, processing or transformation, and output rendering when the change is non-trivial.
• MUST: The command or controller layer MUST act only as an orchestrator.
• MUST: The implementation MUST avoid tight coupling between core behavior and CLI or framework-specific I/O.
• MUST: The design MUST allow future extraction or reuse with minimal changes.
• MUST: The solution MUST remain extensible without requiring major refactoring for adjacent use cases.
• MUST: Data gathering or transformation MUST be isolated from filesystem writes or publishing steps.
• MUST: Generated output ordering and formatting MUST remain deterministic across runs.
• MUST: Re-running the workflow MUST be idempotent or clearly bounded in its side effects.

[coisa]

https://github.com/hajime-matsumoto/phpdocumentor-llms