codebar-ag/documentation

Documentation

When to Apply

• After implementing or refactoring a feature with BackendImplementationAgent, FrontendImplementationAgent, or ImplementationAgent.
• When the behaviour of a public API endpoint, console command, job, or user-facing screen changes.
• When adding a new pattern, skill, or workflow that other developers should follow.
• When onboarding material (README.md, RULES.md, or top-level docs) is out of date with current behaviour.
• Do not apply for internal refactors with no observable behavior change.
• Do not finalize public docs for draft designs that are not implemented yet.

Preconditions

• The relevant code changes are implemented or have at least a stable design from ArchitectAgent.
• You have access to:
  • README.md
  • RULES.md
  • Any feature or skill docs that describe the area being changed
• Tests or basic manual checks have confirmed the new or changed behaviour.

Process

1. Identify the Behaviour to Document

• Summarize the change in 1–3 sentences:
  • What problem does it solve?
  • Who uses it (developer, end user, operator)?
  • What is the primary entry point (route, command, job, UI)?
• Locate the most relevant documentation home for this behaviour:
  • High-level or onboarding: README.md.
  • Project-wide rules or patterns: RULES.md.
  • Skill- or pattern-specific: the corresponding resources/boost/skills/**/SKILL.md.
  • Feature-specific: the closest existing doc file or a new one in the project’s docs area.

Scope Rule: Skill Docs vs Feature Docs

• Update a skill doc when the change defines a reusable rule, pattern, checklist, or anti-pattern.
• Update a feature doc when the change describes one module, endpoint, UI flow, or operator workflow.
• If both changed: put normative guidance in the skill doc, and put concrete behavior in the feature doc.
• Do not duplicate full feature walkthroughs inside resources/boost/skills/**/SKILL.md.

2. Update or Create Documentation

• Prefer updating existing sections over creating new, parallel explanations.
• Keep sections short and scannable:
  • Use clear headings and bullet points.
  • Lead with “what this is” and “when to use it”.
• Focus on:
  • Inputs: routes, request payloads, CLI flags, important configuration.
  • Outputs: responses, side effects (DB changes, events, emails, jobs).
  • Constraints: permissions, limits, feature flags, environment assumptions.
• Link to deeper technical details (code, skills) instead of duplicating them.

3. Add or Refresh Examples

• For backend features:
  • Provide at least one example request/response or CLI invocation.
  • Show the happy path and briefly mention notable error cases.
• For frontend features:
  • Show how a Blade view, Livewire component, or route is used.
  • Mention any important state, props, or events.
• Make examples:
  • Copy-pasteable where reasonable.
  • Minimal: avoid irrelevant noise or unrelated configuration.

4. Validate Against the Code

• Treat code and tests as source of truth, not existing docs.
• Verify behavior directly in routes, controllers, form requests, resources, jobs, and tests.
• Cross-check that the documentation matches the current:
  • Route names, HTTP methods, and URIs.
  • Request fields and validation rules.
  • Response structure or resource fields.
  • Flags, env vars, or configuration keys.
• If something is uncertain:
  • Prefer reading the code or tests over guessing.
  • If truly ambiguous, explicitly call it out as “behaviour depends on …” instead of inventing details.

Conflict Resolution: Docs vs Code

• When docs and code disagree, update docs to match current code/tests in the same change set.
• If code is wrong but docs are right, open/fix code first; do not document intended behavior as if implemented.
• If behavior is intentionally changing, merge docs and code together to avoid stale guidance windows.
• Never keep conflicting statements across README.md, RULES.md, and skill docs after merge.

5. Keep Changelogs and History Manageable

• Avoid narrating every refactor; focus on observable behaviour and how to use the system.
• When behaviour is intentionally changed:
  • Update the documentation as if it had always been correct.
  • Use commit messages or PR descriptions for historical context, not the docs themselves.

6. Report Documentation Changes Clearly

• Use this concise handoff format:
  • Area: [feature / module / onboarding]
  • Docs touched: [README.md, RULES.md, path/to/doc.md]
  • Behavior updates: [what changed for users/developers]
  • Follow-ups: [larger docs or diagrams tracked separately]

Checklists

Execution Checklist

• [ ] Identified which behaviours or features changed.
• [ ] Located the most appropriate docs to update (README, RULES, skill docs, feature docs).
• [ ] Updated or created sections with concise descriptions of behaviour and usage.
• [ ] Added or refreshed at least one practical example where helpful.
• [ ] Cross-checked docs against current routes, requests, responses, and configuration.

Communication Checklist

• [ ] Summarized what changed in the docs (scope, files, and key points).
• [ ] Highlighted any new patterns or skills authors should follow.
• [ ] Noted any follow-up documentation that should be tackled separately (for example, larger guides or diagrams).
• [ ] Included Area/Docs touched/Behavior updates/Follow-ups in the handoff note.

Safety / Things to Avoid

• Do not describe internal implementation details that are likely to change unless they are critical for users.
• Do not duplicate large code snippets that will fall out of sync; prefer links or short, focused examples.
• Do not invent behaviour that does not exist in the code or tests.
• Do not mix unrelated documentation changes into the same batch; keep diffs focused on the current feature or area.

Examples

## Invoice retry endpoint

Use `POST /api/invoices/{invoice}/retry` when retrying a failed payment.
Requires authenticated admin user.

Success: returns `202` and dispatches `RetryInvoicePaymentJob`.
Failure: returns `409` when invoice status is not `failed`.

## Frontend: Invoice list filter

Use query param `status` on `GET /invoices` to pre-filter the Blade view.

Example:
- `/invoices?status=failed` shows only failed invoices.

Livewire component `InvoiceTable` reads `status` from the request and applies the filter on initial render.

References

• README.md: onboarding and high-level behavior only
• RULES.md: project-wide conventions and decision rules
• resources/boost/skills/**/SKILL.md: reusable implementation guidance (not feature walkthroughs)
• Feature docs in project docs area: module-specific behavior, examples, and operational notes