Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -152,4 +152,4 @@ If none of these answers help, open an [issue on GitHub](https://github.com/verc

## Available Components

See the `references/` folder for detailed documentation on each component. Paths beginning with `scripts/` in those references are examples relative to this skill directory, not repository-root scripts. They are component examples, not installed application features.
See the `references/` folder for detailed documentation on each component.
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/references/conversation.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ npx ai-elements@latest add conversation

## Usage with AI SDK

Build a simple conversational UI with `Conversation` and [`PromptInput`](prompt-input.md):
Build a simple conversational UI with `Conversation` and [`PromptInput`](/components/prompt-input):

Add the following component to your frontend:

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/references/image.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ See THIRD-PARTY-NOTICES.md in the repository root for license and provenance.

Displays AI-generated images from the AI SDK.

The `Image` component displays AI-generated images from the AI SDK. It accepts a `Experimental_GeneratedImage` object from the AI SDK's `generateImage` function and automatically renders it as an image.
The `Image` component displays AI-generated images from the AI SDK. It accepts a [`Experimental_GeneratedImage`](/docs/reference/ai-sdk-core/generate-image) object from the AI SDK's `generateImage` function and automatically renders it as an image.

See `scripts/image.tsx` for this example.

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/references/inline-citation.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ npx ai-elements@latest add inline-citation

## Usage with AI SDK

Build citations for AI-generated content using `experimental_generateObject`.
Build citations for AI-generated content using [`experimental_generateObject`](/docs/reference/ai-sdk-ui/use-object).

Add the following component to your frontend:

Expand Down
4 changes: 2 additions & 2 deletions .agents/skills/ai-elements/references/prompt-input.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ npx ai-elements@latest add prompt-input

## Usage with AI SDK

Build a fully functional chat app using `PromptInput`, [`Conversation`](conversation.md) with a model picker:
Build a fully functional chat app using `PromptInput`, [`Conversation`](/components/conversation) with a model picker:

Add the following component to your frontend:

Expand Down Expand Up @@ -368,7 +368,7 @@ See `scripts/prompt-input-tooltip.tsx` for this example.

### Attachments

Attachment components have been moved to a separate module. See the [Attachment](attachments.md) component documentation for details on `<Attachments />`, `<Attachment />`, `<AttachmentPreview />`, `<AttachmentInfo />`, and `<AttachmentRemove />`.
Attachment components have been moved to a separate module. See the [Attachment](/components/attachment) component documentation for details on `<Attachments />`, `<Attachment />`, `<AttachmentPreview />`, `<AttachmentInfo />`, and `<AttachmentRemove />`.

### `<PromptInputActionMenu />`

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/references/reasoning.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,7 @@ export async function POST(req: Request) {

Use the `Reasoning` component when your model outputs thinking content as a single block or continuous stream (Deepseek R1, Claude with extended thinking, etc.).

If your model outputs discrete, labeled steps (search queries, tool calls, distinct thought stages), consider using the [Chain of Thought](chain-of-thought.md) component instead for a more structured visual representation.
If your model outputs discrete, labeled steps (search queries, tool calls, distinct thought stages), consider using the [Chain of Thought](/components/chain-of-thought) component instead for a more structured visual representation.

## Features

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/references/task.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ npx ai-elements@latest add task

## Usage with AI SDK

Build a mock async programming agent using `experimental_generateObject`.
Build a mock async programming agent using [`experimental_generateObject`](/docs/reference/ai-sdk-ui/use-object).

Add the following component to your frontend:

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/ai-elements/references/tool.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ npx ai-elements@latest add tool

## Usage in AI SDK

Build a simple stateful weather app that renders the last message in a tool using `useChat`.
Build a simple stateful weather app that renders the last message in a tool using [`useChat`](/docs/reference/ai-sdk-ui/use-chat).

Add the following component to your frontend:

Expand Down
28 changes: 13 additions & 15 deletions .agents/skills/architecture-governance/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: architecture-governance
description: Apply the repository's architecture policy to code changes by generating a bounded context package, checking module and layer boundaries, and reporting baseline-aware violations. Use for any code change; skip for documentation-only work.
description: Check CCbuddy module and layer boundaries for code changes. Generate bounded context for cross-module or ownership changes; skip documentation-only work.
---

# Architecture governance
Expand All @@ -9,16 +9,16 @@ Use this skill before editing code in the CCbuddy repository. It is a design gui

## Before writing code

1. Identify changed files and their modules with `pnpm architecture:check --changed`.
2. Run `pnpm architecture:context <module-id>` (or the reusable wrapper `node .agents/skills/architecture-governance/scripts/context-package.mjs <module-id>`). Read the target contract, directly referenced contracts, and any existing relevant spec and tests before opening broad implementation files. Do not assume a documentation or test path exists; verify it in the checkout.
3. Write or update the spec before implementation; create its directory when needed. State the behavior, ownership, invariants, failure semantics, and migration boundary in the spec.
4. Make a short design decision before coding:
1. Identify intended files and modules from the task, contracts, and existing tests. Run `pnpm architecture:check --changed` for the current baseline; a clean diff does not identify files you have not edited yet.
2. For cross-module changes, state ownership changes, or an unclear contract, run `pnpm architecture:context <module-id>` (or `node .agents/skills/architecture-governance/scripts/context-package.mjs <module-id>`). For a local change with a known contract, read only the relevant contract, spec, and affected tests; expand when a concrete dependency or evidence gap requires it.
3. Apply the spec and regression-evidence rules in [AGENTS.md](../../../AGENTS.md). New behavior needs a spec before implementation; restoring already specified behavior needs regression evidence, not a duplicate feature document. Pure refactors update docs only when contracts change.
4. For changes to mutable state, asynchronous behavior, or module boundaries, make the relevant design decisions before coding:
- **One owner:** name the single component that owns each piece of mutable state. Other layers read through its contract and send commands; they do not keep a second accepted queue, cache, or derived truth.
- **One path:** reuse an existing command, service, hook, adapter, or contract when it already expresses the behavior. Do not create a parallel helper for the same responsibility.
- **Explicit boundaries:** choose the layer for every new file and the public contract for every cross-module edge. Use the module's declared `layers` and `layerOrder`; a file may import only its own layer or lower ones through their public surface. `domain` is pure (no IO, no `await` on the world), `app` decides side effects through ports, `adapters` executes them, `ui` depends only on this module's `contract.ts`. Quick test: needs `await`? not domain. Knows it is sqlite / MessagePort / a timer? adapters.
- **Explicit time:** for asynchronous or remote behavior, write the event order, owner/lease, idempotency key, stale-result rule, replay/resume boundary, and desktop versus mobile delivery kind before implementation.
- **Bounded context:** prefer the generated reading package over copying whole implementations into the prompt. Read more only when a contract or test proves it is necessary.
5. If the change crosses modules or changes state ownership, include the decision in the spec and add or update the module contract before implementation.
- **Explicit boundaries:** choose the layer for every new file and the public contract for every cross-module edge. Keep `ui → hooks/services → app → domain → adapters` and keep IO out of domain.
- **Explicit time:** for asynchronous or remote behavior, write the event order, owner/lease, idempotency key, stale-result rule, replay/resume boundary, and desktop versus Web/SSH delivery kind before implementation.
- **Bounded context:** use the relevant contracts, specs, and tests. A generated reading package helps when dependencies are unclear; do not require a whole-module reading pass for every local edit.
5. If the change alters a public contract, ownership, or allowed dependency, record that decision in the relevant spec/contract before implementation. Editing files in two modules alone does not require a new document. Use the root task boundary for when to consult the user; ordinary authorized implementation choices proceed autonomously.

Use this compact design sketch while planning stateful changes:

Expand All @@ -32,19 +32,17 @@ For remote or streaming changes, make the delivery boundary explicit:
```text
desktop: continuous ── direct live stream ──┐
├─ same owner and sequence
mobile: replayable ─ snapshot + gap repair ┘
Web/SSH: replayable ─ snapshot + gap repair ┘
```

## During and after editing

6. Keep changes inside the declared module and its allowed layer direction. Add a module dependency or public contract before introducing a cross-module edge.
7. Run `pnpm architecture:check --changed` again after editing. Report new violations separately from baseline violations, along with changed modules, tests, state owners, event-order assumptions, and net line changes.
7. Run `pnpm architecture:check --changed` after editing. Report new violations separately from baseline violations; include owners and event-order assumptions when affected. Follow the root validation matrix, finish after required checks pass, and expand checks only for new edits, failures, or unresolved risks.

The executable policy is `architecture-policy.yaml`; do not duplicate its rules in this file or in AGENTS.md. Use `pnpm architecture:baseline:update` only when a reviewed change intentionally changes the accepted legacy baseline. CI never refreshes baseline automatically.
The executable policy is `architecture-policy.yaml`; keep its detailed rule definitions there. Check the actual managed-module coverage before claiming the gate verifies a boundary: a passing result does not prove unconfigured modules or runtime semantics are correct. Use `pnpm architecture:baseline:update` only when a reviewed change intentionally changes the accepted legacy baseline. CI never refreshes baseline automatically.

When adding source, identify its owning module. If a new managed module is required, register its roots, dependencies, layers and public entrypoints in `architecture-policy.yaml`, and keep the local manifest consistent with that policy. Use the existing managed modules and the fixture below as examples.

For a new managed module, provide `module.ts`, `contract.ts`, `contract.example.ts`, and a short `CONTRACT.md`. Keep runtime and persistence details behind the contract. Prefer typed service calls for one-to-one interactions, commands for state changes, and typed events for broadcast facts.
For a new managed module, provide `module.ts`, `contract.ts`, `contract.example.ts`, `contract.test.ts`, and a short `CONTRACT.md`. Keep runtime and persistence details behind the contract. Prefer typed service calls for one-to-one interactions, commands for state changes, and typed events for broadcast facts.

See [policy-schema.md](references/policy-schema.md), [module-contract.md](references/module-contract.md), and [rule-catalog.md](references/rule-catalog.md) when the change needs their detailed guidance. The [golden-module](references/golden-module) fixture is the smallest compliant example.
See [ai-guidance.md](references/ai-guidance.md) for the anti-patterns this workflow is designed to prevent and the questions an agent must answer before proposing code.
2 changes: 1 addition & 1 deletion .agents/skills/architecture-governance/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
interface:
display_name: Architecture Governance
short_description: Check module boundaries and prepare a bounded code context
default_prompt: Use $architecture-governance before editing code to inspect the affected module, generate its context package, and run the architecture checks before and after the change.
default_prompt: Use $architecture-governance to check affected module boundaries. Generate context for cross-module, ownership, or unclear-contract changes, and run the architecture checks before and after code changes.
10 changes: 5 additions & 5 deletions .agents/skills/architecture-governance/references/ai-guidance.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AI implementation guidance

Architecture governance is a pre-code decision protocol. A coding agent should be able to answer these questions before producing a patch:
Architecture governance is a pre-code decision protocol. Apply the rows relevant to the change: state/ordering questions apply to stateful behavior, and contract questions apply to boundary changes. A local fix with an established contract does not need a new design record. Use the root AGENTS.md for spec requirements and when user input is necessary.

| Decision | Required answer |
| -------- | ------------------------------------------------------------------------------------------------------------- |
Expand All @@ -10,7 +10,7 @@ Architecture governance is a pre-code decision protocol. A coding agent should b
| Layer | Which layer owns the new code, and which direction may imports travel? |
| Reuse | Which existing path already performs part of this work, and why is a new path necessary? |
| Time | What is the event order, idempotency key, stale-result rule, and retry boundary? |
| Remote | Does this preserve desktop continuous delivery and mobile replayable recovery separately? |
| Remote | Does this preserve desktop continuous delivery and ordinary Web/SSH replayable recovery separately? |
| Context | Which contracts, specs, and tests are sufficient for the agent to work without reading whole implementations? |

The agent should reject these shapes during design:
Expand All @@ -20,10 +20,10 @@ The agent should reject these shapes during design:
- a new cache, event bus, adapter, or helper that duplicates an existing path;
- a domain object importing filesystem, process, network, timer, or platform APIs;
- a cross-module deep import added only to avoid defining a contract;
- a remote stream change that mixes desktop `continuous` and mobile `replayable` semantics;
- a remote stream change that mixes desktop `continuous` and ordinary Web/SSH `replayable` semantics;
- a broad refactor that changes unrelated modules without an explicit migration boundary.

The patch description should include a small decision record:
For stateful or cross-boundary changes, capture the relevant decisions in the existing spec/contract or patch description; omit fields that do not apply:

```text
owner: <single state owner>
Expand All @@ -34,4 +34,4 @@ delivery: <desktop-continuous | web-remote-replayable | both>
contracts/spec/tests: <bounded reading and validation set>
```

This guidance complements executable rules. The policy checker can prove import and size constraints; the decision record makes ownership, reuse, and time semantics explicit before an agent writes code.
This guidance complements executable rules. The policy checker verifies configured import and size constraints within its managed coverage; the decision record explains ownership, reuse, and time semantics that the checker cannot prove.
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Golden module

This fixture demonstrates the smallest managed module: a manifest, a narrow port, an example, and no implementation details in the public surface.
This fixture demonstrates the smallest managed module: a manifest, a narrow port, an example, a contract test, and no implementation details in the public surface.
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

A managed module exposes only its contract entrypoint. The contract contains branded identifiers, schemas, typed commands, events, errors, and the semantics required by callers. `domain` stays pure, `app` owns use-case orchestration, `adapters` owns IO and process boundaries, and `ui` consumes the module port/read model.

The example is part of the agent context package. The short `CONTRACT.md` records invariants that types cannot express.
The example and contract test are part of the agent context package. The short `CONTRACT.md` records only invariants that types and tests cannot express.
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
# Policy schema

`architecture-policy.yaml` contains `version: 1`, `modules`, global thresholds and optional exceptions. The current parser is `scripts/architecture/policy.mjs`.
`architecture-policy.yaml` contains `version: 1`, a list of modules, global thresholds, and optional exceptions.

Each module declares an `id`, one or more `roots`, optional `managed: true`, `requires`, `publicEntrypoints`, `layers`, `layerOrder` and `owner`. Existing legacy modules can remain unmanaged. Dependencies must name registered module IDs.
Each module has an `id`, one or more `roots`, optional `managed: true`, `requires`, `provides`, `publicEntrypoints`, and an optional `owner`. Existing modules may remain unmanaged while they are in baseline migration.

Global keys are `maxFileLines`, `maxContractLines`, `maxPublicMethods`, `forbidCycles`, `forbidDeepImports` and `managedOnly`. Layer names and ordering come from each module's configuration; do not assume a global layer list.

The policy owns module topology. A managed module's `module.ts` declares local dependencies; keep it consistent with the policy. Verify supported options in the parser before documenting or using them.
The policy owns path and layer topology. A module's `module.ts` owns its local dependency declaration. Do not add a second hand-maintained dependency graph.
Loading
Loading