Skip to content
Open
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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@

### Added

- **The kickoff interview ships with the skill.** `rules/60-getting-started.md`
is now also published as `skills/ucsd-decorator/references/getting-started.md`,
like the accessibility and security rules. The skill pointed at the
project's `DECORATOR.md` for the six questions, which exists only once the
kit is installed, so "help me get started" had nothing to ask without it. A
test holds every exported reference page to the whole rule. See #12.
- **A `ucsd-decorator-kit` skill for the TritonAI Skills Library.** A short
pointer at `library/tritonai/ucsd-decorator-kit/` that tells an agent with no
kit installed how to get it: `npx ucsd-decorator-kit@latest init` in an empty
Expand Down
4 changes: 2 additions & 2 deletions library/tritonai/ucsd-decorator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,8 +175,7 @@ template, never from recall.

When a developer asks to get started — "help me get started", "where do I
begin", "start a new project" — run the kickoff interview before writing any
markup. Its full text is "Getting started — the kickoff interview" in the
project's `DECORATOR.md`, compiled from the kit's `rules/60-getting-started.md`.
markup. Its full text is in `references/getting-started.md`.
Ask its six questions in one message, recommend a layout and modules with links
to the Decorator Kit Developer Guide at
`https://developer.ucsd.edu/design/decorator/user-guide/`, let the developer
Expand Down Expand Up @@ -482,6 +481,7 @@ the source file to restore from. Use it; do not guess.
table written from live pages; where it disagrees with the references above,
prefer them
- `references/component-inventory.md` — kitchen sink, widgets, modules
- `references/getting-started.md` — the kickoff interview and build brief
- `references/accessibility.md` — full WCAG 2.1 AA rule set
- `references/security.md` — full IS-3 / PPM 135-3 rule set
- `references/distribution.md` — how Decorator is published, and what a consuming project should depend on
Expand Down
99 changes: 99 additions & 0 deletions library/tritonai/ucsd-decorator/references/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
<!-- Generated by scripts/compile-rules.mjs from rules/. Do not edit directly. -->

# Getting started — the kickoff interview

When a developer asks to get started — "help me get started", "where do I
begin", "start a new project", "what should I build this with" — do not start
writing markup. Run this interview first. Skip it when the request already
answers its questions — a named template, a page name, and the pieces to build —
and ask only what is missing.

The interview exists for developers who know what the app has to do but not
what it should look like: their answers pick the layout, modules, and patterns,
so the first iteration is already close to the goal and stays on brand.

## The visual guide

Every recommendation links a card in the Decorator Kit Developer Guide, so the
developer can see it before agreeing to it. Base URL:
`https://developer.ucsd.edu/design/decorator/user-guide/`. The anchors below
are relative to it — write them out as full links.

## Round 1 — ask all six at once

Ask in one message, as a numbered list with lettered options, so the developer
can reply "1b, 2 students checking waitlists, 3b…". If your environment has a
structured multiple-choice tool, you may use it instead. Always allow a
free-text answer.

1. **What are you building?** (a) a department or information site
(b) a request, intake, or multi-step application form (c) a dashboard or
status board (d) a directory, search, or records admin tool (e) a knowledge
base or help articles (f) something else — describe it in a sentence.
2. **Who uses it, and what is the one thing they must be able to do?** For
example: "students — check whether they got off a waitlist."
3. **Which campus area?** (a) advising (b) enrollment and courses (c) research
(d) housing (e) IT services (f) facilities and energy (g) library (h) HR
(i) other or none.
4. **How will it be built and hosted?** (a) static HTML (b) a JavaScript
framework such as React or Vue (c) server-rendered templates (d) Cascade CMS
(e) not sure. The Decorator is Bootstrap 3 and jQuery whatever language the
app is written in; this decides where the canvas lives, not the look.
5. **What data does it touch?** (a) public information only (b) it needs campus
sign-in (c) student records, personal, or health data (d) not sure.
6. **Site name**, and a short form of it for phones — a word or an acronym.

## Round 2 — recommend, link, and let the developer choose

Map the answers with these tables. Link every card you recommend.

| Building | Suggested layout | Guide cards |
|---|---|---|
| (a) information site | `homepage.html` for the landing page, `two-column.html` for inner pages | `index.html#r-dept`, `#lay-home`, `#modules`, `#m-tiles`, `#m-news`, `#m-events` |
| (b) request or application | `two-column.html` or `blank-slate.html` | `index.html#r-form`, `#c-forms`, `#w-wiz`, `app-patterns.html#pat-shell`, `#shell-steps` |
| (c) dashboard | `blank-slate.html` | `index.html#r-dash`, `app-patterns.html#dash-workflow`, `#shell-dashboard`, `#blk-kpi`, `#blk-status`, `#blk-filter` |
| (d) directory, search, admin | `blank-slate.html` or `two-column.html` | `index.html#r-dir`, `#w-dt`, `#c-tables`, `app-patterns.html#shell-search`, `#shell-admin`, `#shell-record` |
| (e) knowledge base | `two-column.html` | `index.html#r-kb`, `#c-drawer`, `#c-crumbs` |

| Campus area | Dashboard example to borrow from |
|---|---|
| advising · enrollment · research · housing | `app-patterns.html#dash-advising` · `#dash-enroll` · `#dash-research` · `#dash-housing` |
| IT · facilities · library · HR | `app-patterns.html#dash-its` · `#dash-energy` · `#dash-library` · `#dash-hr` |

- **Build (b) or (c):** the canvas is still `main#main-content`. If the
project uses a component library, it goes in `canvas-components/` — link
`app-patterns.html#brand-layer`. **(d) Cascade:** content goes into the
page's canvas region only. **(e):** recommend static HTML.
- **Data (b), (c), or (d):** say that the security rules apply from the first
commit — campus SSO, no real records in placeholder content, nothing
sensitive in URLs or logs.

**Recommend a layout, but do not choose it.** Link all four layout cards —
`index.html#lay-blank`, `#lay-two`, `#lay-three`, `#lay-home` — say which one
you suggest and why in one sentence, and wait for the developer to pick. The
template-selection rule still holds: the choice is theirs.

## Write the brief before building

Once the layout is chosen, save `BRIEF.md` at the project root and show it:

```markdown
# Build brief — <site name> (<short form>)

- **Building:** <one sentence> · **For:** <audience> · **Must do:** <the one task>
- **Layout:** <template> saved as <file name>
- **Stack:** <build and hosting> · **Data:** <classification, sign-in>
- **Canvas, top to bottom:** 1. <module or pattern> — <purpose> (<guide link>) …
- **Placeholders:** <which content is not real yet>
```

Build from the brief, following every kit rule: copy the chosen template,
rewrite its asset paths to `cdn.ucsd.edu`, set the site name and its short form,
fill only the canvas, and sync every navigation surface. Then run `verify`.

## Finish with next steps

End the first iteration with: what was built, `verify`'s result, the review
prompt at `index.html#g-review`, and two or three next prompts taken from the
guide cards you linked. Later sessions read `BRIEF.md` before changing the
page, and update it when the plan changes.
1 change: 1 addition & 0 deletions scripts/lib/rules.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ const NO_LIBRARY_NOTES =
export const REFERENCE_EXPORTS = new Map([
["40-accessibility.md", "accessibility.md"],
["50-security.md", "security.md"],
["60-getting-started.md", "getting-started.md"],
]);

export const TARGETS = [
Expand Down
4 changes: 2 additions & 2 deletions skills/ucsd-decorator/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,8 +175,7 @@ template, never from recall.

When a developer asks to get started — "help me get started", "where do I
begin", "start a new project" — run the kickoff interview before writing any
markup. Its full text is "Getting started — the kickoff interview" in the
project's `DECORATOR.md`, compiled from the kit's `rules/60-getting-started.md`.
markup. Its full text is in `references/getting-started.md`.
Ask its six questions in one message, recommend a layout and modules with links
to the Decorator Kit Developer Guide at
`https://developer.ucsd.edu/design/decorator/user-guide/`, let the developer
Expand Down Expand Up @@ -482,6 +481,7 @@ the source file to restore from. Use it; do not guess.
table written from live pages; where it disagrees with the references above,
prefer them
- `references/component-inventory.md` — kitchen sink, widgets, modules
- `references/getting-started.md` — the kickoff interview and build brief
- `references/accessibility.md` — full WCAG 2.1 AA rule set
- `references/security.md` — full IS-3 / PPM 135-3 rule set
- `references/distribution.md` — how Decorator is published, and what a consuming project should depend on
Expand Down
99 changes: 99 additions & 0 deletions skills/ucsd-decorator/references/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
<!-- Generated by scripts/compile-rules.mjs from rules/. Do not edit directly. -->

# Getting started — the kickoff interview

When a developer asks to get started — "help me get started", "where do I
begin", "start a new project", "what should I build this with" — do not start
writing markup. Run this interview first. Skip it when the request already
answers its questions — a named template, a page name, and the pieces to build —
and ask only what is missing.

The interview exists for developers who know what the app has to do but not
what it should look like: their answers pick the layout, modules, and patterns,
so the first iteration is already close to the goal and stays on brand.

## The visual guide

Every recommendation links a card in the Decorator Kit Developer Guide, so the
developer can see it before agreeing to it. Base URL:
`https://developer.ucsd.edu/design/decorator/user-guide/`. The anchors below
are relative to it — write them out as full links.

## Round 1 — ask all six at once

Ask in one message, as a numbered list with lettered options, so the developer
can reply "1b, 2 students checking waitlists, 3b…". If your environment has a
structured multiple-choice tool, you may use it instead. Always allow a
free-text answer.

1. **What are you building?** (a) a department or information site
(b) a request, intake, or multi-step application form (c) a dashboard or
status board (d) a directory, search, or records admin tool (e) a knowledge
base or help articles (f) something else — describe it in a sentence.
2. **Who uses it, and what is the one thing they must be able to do?** For
example: "students — check whether they got off a waitlist."
3. **Which campus area?** (a) advising (b) enrollment and courses (c) research
(d) housing (e) IT services (f) facilities and energy (g) library (h) HR
(i) other or none.
4. **How will it be built and hosted?** (a) static HTML (b) a JavaScript
framework such as React or Vue (c) server-rendered templates (d) Cascade CMS
(e) not sure. The Decorator is Bootstrap 3 and jQuery whatever language the
app is written in; this decides where the canvas lives, not the look.
5. **What data does it touch?** (a) public information only (b) it needs campus
sign-in (c) student records, personal, or health data (d) not sure.
6. **Site name**, and a short form of it for phones — a word or an acronym.

## Round 2 — recommend, link, and let the developer choose

Map the answers with these tables. Link every card you recommend.

| Building | Suggested layout | Guide cards |
|---|---|---|
| (a) information site | `homepage.html` for the landing page, `two-column.html` for inner pages | `index.html#r-dept`, `#lay-home`, `#modules`, `#m-tiles`, `#m-news`, `#m-events` |
| (b) request or application | `two-column.html` or `blank-slate.html` | `index.html#r-form`, `#c-forms`, `#w-wiz`, `app-patterns.html#pat-shell`, `#shell-steps` |
| (c) dashboard | `blank-slate.html` | `index.html#r-dash`, `app-patterns.html#dash-workflow`, `#shell-dashboard`, `#blk-kpi`, `#blk-status`, `#blk-filter` |
| (d) directory, search, admin | `blank-slate.html` or `two-column.html` | `index.html#r-dir`, `#w-dt`, `#c-tables`, `app-patterns.html#shell-search`, `#shell-admin`, `#shell-record` |
| (e) knowledge base | `two-column.html` | `index.html#r-kb`, `#c-drawer`, `#c-crumbs` |

| Campus area | Dashboard example to borrow from |
|---|---|
| advising · enrollment · research · housing | `app-patterns.html#dash-advising` · `#dash-enroll` · `#dash-research` · `#dash-housing` |
| IT · facilities · library · HR | `app-patterns.html#dash-its` · `#dash-energy` · `#dash-library` · `#dash-hr` |

- **Build (b) or (c):** the canvas is still `main#main-content`. If the
project uses a component library, it goes in `canvas-components/` — link
`app-patterns.html#brand-layer`. **(d) Cascade:** content goes into the
page's canvas region only. **(e):** recommend static HTML.
- **Data (b), (c), or (d):** say that the security rules apply from the first
commit — campus SSO, no real records in placeholder content, nothing
sensitive in URLs or logs.

**Recommend a layout, but do not choose it.** Link all four layout cards —
`index.html#lay-blank`, `#lay-two`, `#lay-three`, `#lay-home` — say which one
you suggest and why in one sentence, and wait for the developer to pick. The
template-selection rule still holds: the choice is theirs.

## Write the brief before building

Once the layout is chosen, save `BRIEF.md` at the project root and show it:

```markdown
# Build brief — <site name> (<short form>)

- **Building:** <one sentence> · **For:** <audience> · **Must do:** <the one task>
- **Layout:** <template> saved as <file name>
- **Stack:** <build and hosting> · **Data:** <classification, sign-in>
- **Canvas, top to bottom:** 1. <module or pattern> — <purpose> (<guide link>) …
- **Placeholders:** <which content is not real yet>
```

Build from the brief, following every kit rule: copy the chosen template,
rewrite its asset paths to `cdn.ucsd.edu`, set the site name and its short form,
fill only the canvas, and sync every navigation surface. Then run `verify`.

## Finish with next steps

End the first iteration with: what was built, `verify`'s result, the review
prompt at `index.html#g-review`, and two or three next prompts taken from the
guide cards you linked. Later sessions read `BRIEF.md` before changing the
page, and update it when the plan changes.
21 changes: 20 additions & 1 deletion test/rules.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
import path from "node:path";
import { after, before, describe, it } from "node:test";
import { fileURLToPath } from "node:url";
import { MEMORY_FILE_WARN_CHARS, ON_DEMAND_FILE, TARGETS, renderRuleFiles } from "../scripts/lib/rules.mjs";
import { MEMORY_FILE_WARN_CHARS, ON_DEMAND_FILE, REFERENCE_EXPORTS, TARGETS, renderRuleFiles } from "../scripts/lib/rules.mjs";

// The rule files load in full in every session; DECORATOR.md is read only when
// one of them names the task in front of the agent. These tests hold the split
Expand Down Expand Up @@ -200,6 +200,25 @@ describe("the kit's own rules", () => {
}
});

// A skill installed without the kit has no DECORATOR.md, so its reference
// pages carry each exported rule whole, on-demand sections included.
it("publish each exported rule whole in the skill's reference pages", async () => {
const { outputs: published } = await renderRuleFiles({ rulesDir: path.join(ROOT, "rules"), references: true });
for (const [source, destination] of REFERENCE_EXPORTS) {
const page = published.get(`skills/ucsd-decorator/references/${destination}`);
assert.ok(page, `rules/${source} has no reference page`);
assert.doesNotMatch(page, /DECORATOR\.md/, `references/${destination} sends the agent to ${ON_DEMAND_FILE}`);
assert.doesNotMatch(page, /<!--\s*on-demand/, `references/${destination} kept an on-demand marker`);
}

// The interview moves whole to DECORATOR.md in the rule files; the skill's
// copy is the only one an agent without the kit can read.
assert.match(
published.get("skills/ucsd-decorator/references/getting-started.md"),
/^## Round 1 — ask all six at once$/m,
);
});

it("never import DECORATOR.md, which would load it in every session", () => {
for (const [file, contents] of outputs) {
assert.doesNotMatch(contents, /(^|\s)@DECORATOR\.md/, `${file} imports ${ON_DEMAND_FILE}`);
Expand Down