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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .github/skills/developer/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,30 @@ Use this reference for gh-aw technical specs and development guidelines across c

Use this section for the detailed day-to-day command flow that was intentionally removed from `AGENTS.md` to keep first-run ambient context small.

### Sandbox-compatible commands

- Run commands from the active worktree, never the main checkout or a sibling
worktree. Each shell starts fresh; specify the working directory in each
command. From the repository root, use `npm --prefix docs run <script>` for
docs scripts, not bare `npm run <script>`.
- Use literal `$TMPDIR` paths for scratch files and writable caches, not
`/tmp`, resolved macOS temp paths, or system directories. When cache writes
need isolation, prefix npm commands with
`npm_config_cache="$TMPDIR/gh-aw-npm-cache"` and Go commands with
`GOCACHE="$TMPDIR/gh-aw-go-build" GOMODCACHE="$TMPDIR/gh-aw-go-mod"`.
Restore local dependencies only after a manifest change or missing-tool
failure; do not install tools globally.
- Prefer the smallest focused check. Docs title changes use
`npm --prefix docs run test:titles`. Full docs builds also require the
`githubnext/agentics` workflow sources: set `AGENTICS_WORKFLOWS_DIR` to an
explicitly available dependency directory rather than relying on the
default sibling path outside the worktree. Missing sources are a dependency
blocker, not a sandbox denial; do not fabricate replacement workflows.
- Attempt commands inside the sandbox. On a path denial, stop operations on
that path, report the sandbox restriction, and request a policy update.
Do not retry through another tool, change permissions, or rerun outside the
sandbox. Missing approvals and ordinary build errors are not path denials.

### Validation checkpoints

Run validation in tiers. Keep formatting and focused tests in the inner loop;
Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ Load task-specific guidance lazily through local skills.
8. Execute plans without confirmation. In autopilot, act autonomously; never ask "Should I proceed?" or equivalent.
9. **Instruction packing**: Copilot CLI prompt-file queries may expose only the first **8,000 UTF-8 bytes**, including metadata. Keep objective, mandatory constraints, task routes, verification and stop conditions within **7,500 bytes**. Put examples/detail afterward with early links. Use short, explicit imperatives; preserve semantics, safety and failure behavior. Follow `.github/skills/prompt-token-efficiency/SKILL.md`; run `make check-instruction-prefixes` for maintained entry points.
10. **Grading contract**: Follow `.github/skills/operational-value-designer/SKILL.md`. Built-ins compute over the in-memory unified session in conclusion. Custom `graders.<distinct-id>.script` JavaScript and reserved `graders.operational-value.script` JavaScript run only in the separate graders job; operational value returns ordered `{id,value}` metrics whose first value is primary. Removed `graders.operational-value.run` declarations must fail with migration guidance to `script`; never ignore or translate them. Never add user code or steps to conclusion. Adopt workflow semantics and grader acceptance rules together; corrections are prospective and prior results are never rewritten.
11. **Sandbox-compatible commands**: Work in the active worktree; use `$TMPDIR` for scratch and writable tool caches. Follow the `developer` skill's sandbox command guidance. Report path denials; do not retry outside the sandbox or through another tool.

## Upstream-managed workflow sources (read-only in this repo)

Expand Down
6 changes: 6 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,12 @@ Inside of your Astro + Starlight project, you'll see the following folders and f

Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.

Starlight renders the frontmatter `title` automatically. An opening Markdown
`#` heading with the same text is deduplicated at build time, ignoring inline
formatting, capitalization, and whitespace. Its anchor remains available for
existing links. Distinct headings and headings after body content are preserved.
Run `npm run test:titles` to check this behavior for Markdown and MDX pages.

Images can be added to `src/assets/` and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in the `public/` directory.
Expand Down
3 changes: 2 additions & 1 deletion docs/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import remarkStripEmojis from "./src/lib/remark/stripEmojis.js";
import remarkTableDataLabels from "./src/lib/remark/tableDataLabels.js";
import remarkInlineMarkdownInHtml from "./src/lib/remark/inlineMarkdownInHtml.js";
import remarkAgenticsWorkflow from "./src/lib/remark/agenticsWorkflow.js";
import rehypeDeduplicateTitle from "./src/lib/rehype/deduplicateTitle.js";
import rehypeTableWrapper from "./src/lib/rehype/tableWrapper.js";
import cracktroMetadata from "./src/lib/cracktro/integration.js";
import redirectFragments from "./src/lib/redirect-fragments.js";
Expand Down Expand Up @@ -41,7 +42,7 @@ export default defineConfig({
markdown: {
processor: unified({
remarkPlugins: [remarkStripEmojis, remarkTableDataLabels, remarkInlineMarkdownInHtml, [remarkAgenticsWorkflow, { sourceDirectory: agenticsWorkflowsDirectory }]],
rehypePlugins: [rehypeTableWrapper],
rehypePlugins: [rehypeDeduplicateTitle, rehypeTableWrapper],
}),
},
vite: {
Expand Down
1 change: 1 addition & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
"check:cracktro": "tsc -p tsconfig.cracktro.json",
"test": "playwright test",
"test:jsonld": "ASTRO_TELEMETRY_DISABLED=1 node --test tests/jsonld-security.test.mjs",
"test:titles": "ASTRO_TELEMETRY_DISABLED=1 node --test tests/page-titles.test.mjs src/lib/rehype/deduplicateTitle.test.mjs",
"test:ui": "playwright test --ui",
"test:debug": "playwright test --debug"
},
Expand Down
72 changes: 72 additions & 0 deletions docs/src/lib/rehype/deduplicateTitle.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
// @ts-check
import { rehypeHeadingIds } from "@astrojs/markdown-remark";

/**
* Keep Starlight's page title instead of a matching opening Markdown h1.
* @type {import('@astrojs/markdown-remark').RehypePlugin}
*/
export default function rehypeDeduplicateTitle() {
const addHeadingIds = rehypeHeadingIds();
if (typeof addHeadingIds !== "function") {
throw new TypeError("Astro's heading ID plugin must return a transformer");
}

return (tree, file) => {
const frontmatter = file.data.astro?.frontmatter;
const title = frontmatter?.hero?.title ?? frontmatter?.title;
if (typeof title !== "string" || !title.trim() || isLandingPage(file.path)) return;

const heading = tree.children.find(isContent);
if (heading?.type !== "element" || heading.tagName !== "h1") return;
const text = headingText(heading);
if (text === null || normalizeTitle(text) !== normalizeTitle(title)) return;

// Generate IDs before removing the heading to preserve existing deep links
// and slug suffixes on subsequent headings with the same text.
addHeadingIds(tree, file, error => {
if (error) throw error;
});
heading.tagName = "span";
heading.children = [];
Comment thread
pelikhan marked this conversation as resolved.
Resolved
};
}

/** @param {import('unist').Node} node */
function isContent(node) {
if (node.type === "comment" || node.type === "mdxjsEsm" || isCommentExpression(node)) return false;
if ("value" in node && typeof node.value === "string") {
if (node.type === "text" && !node.value.trim()) return false;
Comment thread
pelikhan marked this conversation as resolved.
Resolved
if (node.type === "raw" && /^\s*<!--[\s\S]*-->\s*$/.test(node.value)) return false;
}
return true;
}

/** @param {string | undefined} filePath */
function isLandingPage(filePath) {
return typeof filePath === "string" && /(?:^|[/\\])src[/\\]content[/\\]docs[/\\]index\.mdx?$/.test(filePath);
}

/** @param {import('unist').Node} node */
function isCommentExpression(node) {
if (node.type !== "mdxFlowExpression" || !node.data || !("estree" in node.data)) return false;
const program = node.data.estree;
return typeof program === "object" && program !== null && "body" in program && Array.isArray(program.body) && program.body.length === 0;
}

/**
* Compare visible text, but keep headings containing images or expressions.
* @param {import('hast').Nodes} node
* @returns {string | null}
*/
function headingText(node) {
if (node.type === "text") return node.value;
if (node.type !== "element" || node.tagName === "img") return null;
if (node.tagName === "br") return " ";
const children = node.children.map(headingText);
return children.includes(null) ? null : children.join("");
}

/** @param {string} title */
function normalizeTitle(title) {
return title.normalize("NFC").trim().replace(/\s+/g, " ").toLowerCase();
}
51 changes: 51 additions & 0 deletions docs/src/lib/rehype/deduplicateTitle.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import { fileURLToPath } from "node:url";
import { compile } from "@mdx-js/mdx";
import rehypeDeduplicateTitle from "./deduplicateTitle.js";

async function transform(value, path = "page.mdx", title = "Page Title") {
let result;
await compile(
{
value,
path: fileURLToPath(new URL(`../../content/docs/${path}`, import.meta.url)),
data: { astro: { frontmatter: { title } } },
},
{
rehypePlugins: [
rehypeDeduplicateTitle,
() => tree => {
result = tree;
},
],
}
);
return result.children.find(node => node.type === "element");
}

for (const extension of ["md", "mdx"]) {
test(`${extension}: the landing page retains its matching Markdown title`, async () => {
const heading = await transform("# Home", `index.${extension}`, "Home");
assert.equal(heading.tagName, "h1");
});

test(`${extension}: a nested index still deduplicates its matching title`, async () => {
const heading = await transform("# Page Title", `guide/index.${extension}`);
assert.equal(heading.tagName, "span");
});
}

for (const expression of ["{/* Introductory comment */}", "{/* First comment */ /* Second comment */}", "{// Introductory comment\n}"]) {
test(`comment-only MDX expressions do not precede the title: ${expression}`, async () => {
const heading = await transform(`${expression}\n\n# Page Title`);
assert.equal(heading.tagName, "span");
});
}

for (const expression of ['{"Visible introduction"}', '{/* Before */ "Visible introduction" /* After */}', "{/* Before */ <p>Visible introduction</p> /* After */}"]) {
test(`renderable MDX expressions keep a later matching title: ${expression}`, async () => {
const heading = await transform(`${expression}\n\n# Page Title`);
assert.equal(heading.tagName, "h1");
});
}
131 changes: 131 additions & 0 deletions docs/tests/page-titles.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
import assert from "node:assert/strict";
import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { after, before, test } from "node:test";
import { fileURLToPath } from "node:url";
import { build } from "astro";

const docsRoot = fileURLToPath(new URL("../", import.meta.url));
let root;

const cases = [
{
name: "matching",
body: "<!-- Introductory comment -->\n\n# Page Title\n\nContent.\n\n| Column |\n| --- |\n| Cell |\n\n## Page Title",
headings: 1,
anchor: "page-title",
section: "page-title-1",
},
{
name: "formatted",
title: "A Smart Title & Links",
body: "# A **smart** `Title` &amp; [Links](#details)\n\n## Details",
headings: 1,
anchor: "a-smart-title--links",
},
{ name: "distinct", body: "# A different title", headings: 2 },
{ name: "later", body: "Introduction.\n\n# Page Title", headings: 2 },
{ name: "section", body: "## Page Title", headings: 1, section: "page-title" },
{ name: "code", body: "```md\n# Page Title\n```\n\n# Page Title", headings: 2 },
{ name: "no-heading", body: "Content without a heading.", headings: 1 },
{ name: "image", body: "# Page Title ![Badge](data:image/svg+xml,%3Csvg%3E%3C/svg%3E)", headings: 2 },
{
name: "hero",
extra: 'hero:\n title: "Hero Title"\n',
body: "# Hero Title",
headings: 1,
anchor: "hero-title",
},
{
name: "distinct-hero",
extra: 'hero:\n title: "Hero Title"\n',
body: "# Page Title",
headings: 2,
},
];

before(async () => {
await mkdir(join(docsRoot, ".astro"), { recursive: true });
root = await mkdtemp(join(docsRoot, ".astro/page-titles-"));
const content = join(root, "src/content/docs");
await mkdir(content, { recursive: true });
Comment thread
pelikhan marked this conversation as resolved.
Resolved
await writeFile(
join(root, "astro.config.mjs"),
`
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import productionConfig from ${JSON.stringify(join(docsRoot, "astro.config.mjs"))};
export default defineConfig({
site: 'https://github.github.com',
base: '/gh-aw/',
markdown: productionConfig.markdown,
integrations: [starlight({
title: 'Docs',
components: { PageTitle: ${JSON.stringify(join(docsRoot, "src/components/PageTitle.astro"))} },
})],
});
`
);
await writeFile(
join(root, "src/content.config.ts"),
`
import { defineCollection } from 'astro:content';
import { docsLoader } from '@astrojs/starlight/loaders';
import { docsSchema } from '@astrojs/starlight/schema';
export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) };
`
);
await writeFile(join(content, "index.md"), "---\ntitle: Home\n---\n# Home\n");
for (const extension of ["md", "mdx"]) {
for (const scenario of cases) {
const imports = extension === "mdx" ? "import { Card } from '@astrojs/starlight/components';\n\n" : "";
const body = extension === "mdx" && scenario.name === "matching" ? scenario.body.replace("<!-- Introductory comment -->\n\n", "{/* Introductory comment */}\n\n") : scenario.body;
await writeFile(join(content, `${scenario.name}-${extension}.${extension}`), `---\ntitle: ${JSON.stringify(scenario.title ?? "Page Title")}\n${scenario.extra ?? ""}---\n${imports}${body}\n`);
}
await writeFile(join(content, "expression.mdx"), '---\ntitle: Page Title\n---\n# Page Title {"details"}\n');
}
await writeFile(join(content, "unified-agent-session-specification.md"), await readFile(join(docsRoot, "src/content/docs/specs/unified-agent-session-specification.md"), "utf8"));
await build({ root, logLevel: "silent" });
});

after(async () => {
if (root) await rm(root, { recursive: true, force: true });
});

for (const extension of ["md", "mdx"]) {
for (const scenario of cases) {
test(`${extension}: ${scenario.name} keeps only redundant opening titles out of the output`, async () => {
const html = await readFile(join(root, "dist", `${scenario.name}-${extension}`, "index.html"), "utf8");
assert.equal([...html.matchAll(/<h1\b/g)].length, scenario.headings);
assert.match(html, /<h1 id="_top"/);
if (scenario.anchor) {
assert.ok(html.includes(`<span id="${scenario.anchor}"></span>`), "original title anchor is preserved");
assert.ok(!html.includes(`href="#${scenario.anchor}"`), "duplicate title is not in the table of contents");
}
if (scenario.name === "matching") {
assert.match(html, /class="table-scroll-wrapper"/);
assert.match(html, /<td data-label="Column">Cell<\/td>/);
}
if (scenario.section) assert.ok(html.includes(`id="${scenario.section}"`), "section heading keeps its original slug");
});
}
}

test("the unified session specification renders its title once", async () => {
const html = await readFile(join(root, "dist/unified-agent-session-specification/index.html"), "utf8");
assert.equal([...html.matchAll(/<h1\b/g)].length, 1);
assert.match(html, /<h1 id="_top"[^>]*>Unified Agent Session Specification<\/h1>/);
assert.match(html, /<span id="unified-agent-session-specification"><\/span>/);
});

test("the landing page keeps its own title", async () => {
const html = await readFile(join(root, "dist/index.html"), "utf8");
assert.equal([...html.matchAll(/<h1\b/g)].length, 1);
assert.match(html, /<h1 id="home">Home<\/h1>/);
});

test("headings with MDX expressions keep their dynamic content", async () => {
const html = await readFile(join(root, "dist/expression/index.html"), "utf8");
assert.equal([...html.matchAll(/<h1\b/g)].length, 2);
assert.match(html, /Page Title details<\/h1>/);
});
Loading