Authoring Projects

Authoring Projects

Create a private-by-default project from a current in-repository reference, then wire every consumer before customizing the component.

Required context

1. Read the repository AGENTS.md.
2. Read references/integration-checklist.md.
3. Use the authoring-components skill for the component class, API, examples, and five test files.
4. Use the guidance-build-system skill for Wireit changes and the authoring-testing skill when modifying tests.
5. Read projects/internals/RELEASE.md only when the user wants the package published.

Workflow

1. Confirm the kebab-case project/component name, purpose, package description, and whether the project is private or publish-ready. Default the component name to the project name and keep a new scaffold private.

2. Inspect git status, confirm projects/<name> does not exist, and preserve unrelated work.

3. Preview the deterministic scaffold from the repository root:

   node .agents/skills/authoring-projects/scripts/scaffold-project.mjs \
     --name <component-name> \
     --description "<package and component description>" \
     --dry-run
   

4. Review the planned paths, then rerun without --dry-run. Pass --reference <project-name> when another standalone project is a better structural match.

5. Customize the placeholder component through the authoring-components workflow. Keep index.ts side-effect free, isolate registration in define.ts, use @since 0.0.0, and make the @documentation URL match the generated site route.

6. Refresh generated workspace state:

   mise exec -- pnpm install
   mise exec -- pnpm run format:fix
   mise exec -- pnpm run notice
   

7. Run the project checks listed in its DEVELOPMENT.md, then verify the repository integrations:

   mise exec -- pnpm -C projects/<component-name> run ci
   mise exec -- pnpm -C projects/<component-name> run test:lighthouse
   mise exec -- pnpm -C projects/internals/metadata run generate:api
   mise exec -- pnpm -C projects/internals/metadata run build
   mise exec -- pnpm -C projects/site run build
   mise exec -- pnpm run lint:knip
   

8. Use targeted project checks for isolated changes. Because scaffolding affects cross-project interfaces, generated artifacts, and more than one package, run broader CI from the repository root after the targeted checks:

   mise exec -- pnpm run ci
   

   Inspect the final diff for generated artifacts, missing build edges, copied visual baselines, and unrelated lockfile churn.

Guardrails

• Never overwrite an existing project or reuse another component's visual baselines.
• Declare every generated metadata/site input with its matching Wireit build dependency.
• Keep site-only workspace packages in projects/site dev dependencies and its workspace-scoped dependency-lint ignore because Eleventy creates their imports dynamically.
• Include CSS linting and use the repository-root stylelint path (../../stylelint.config.mjs) from a top-level project.
• Do not create tags, publish packages, edit release wiring, or make a private project public without explicit user authorization.
• Treat commit c88b885b as historical evidence, not a byte-for-byte template; the checklist records the defects that the scaffold must avoid.