feat(skills): restructure docs + add PR lifecycle skills

[breadoncee]

Summary

• Restructure .chalk/docs/ from numbered files (0_PRODUCT_PROFILE.md) to PROFILE.md convention — one canonical entry point per vertical
• Expand chalk.json from 4 fields to a full machine-readable project identity (dev server, routes, source layout, test/build commands) with JSON Schema
• Add 5 new lifecycle skills completing the issue-to-PR workflow: work-issue, commit, capture-pr-visuals, create-pr, validate-chalk

Changes

Foundation (docs restructure)

• docs/chalk.schema.json — JSON Schema defining the expanded chalk.json contract with project, dev, test, build, routes, and sourceLayout sections
• setup-chalk v2.0.0 — Generates expanded chalk.json + new PROFILE.md structure. Includes framework detection table, route scanning, source layout mapping, and v1→v2 migration guide
• setup-docs v2.0.0 — Enriches chalk.json with fields setup-chalk couldn't detect (routes, source layout) and populates PROFILE stubs with deep codebase analysis
• validate-chalk — Audits chalk.json schema compliance and docs completeness. Reports gaps with actionable fix suggestions. Optional fix mode auto-repairs issues

Lifecycle skills

• work-issue — Fetches GitHub issue → creates conventionally-named branch → reads chalk.json for project context → sets up implementation todo list
• commit — Analyzes diffs → stages specific files → creates conventional commit messages. Supports granular commits for unrelated changes
• capture-pr-visuals — Reads chalk.json for dev server URL and routes → launches Playwright via npx → captures screenshots + GIF recordings → commits to .github/pr-screenshots/. Falls back to auto-discovery if no chalk docs exist
• create-pr — Full PR workflow with gh pr create. Auto-embeds screenshots from .github/pr-screenshots/ in a Visual Preview section. Uses chalk.json test/dev commands for test plan

Why this matters

Skills like capture-pr-visuals need to answer "what's the dev URL? what routes exist? what framework is this?" — previously that info was scattered across 4+ markdown files with no predictable location. Now chalk.json is the single source of truth that any skill reads first.

Test plan

• scripts/validate-skills.sh passes (17 skills validated)
• Run /setup-chalk on a fresh repo and verify expanded chalk.json + PROFILE.md structure
• Run /validate-chalk on a project with existing .chalk/ to check gap reporting
• Run /capture-pr-visuals on a running web app to verify Playwright capture flow
• Run /work-issue 42 to verify branch creation and context setup
• Run /commit to verify staging and conventional commit workflow
• Run /create-pr to verify visual preview section embedding

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Chalk system's ability to understand and automate development workflows. By centralizing comprehensive project metadata in an expanded chalk.json and standardizing documentation, it provides a single source of truth for skills. The addition of new lifecycle skills streamlines the entire development process, from picking up an issue to creating a pull request with automated visual previews, making the system more robust and efficient for developers.

Highlights

• Documentation Restructure: Restructured the .chalk/docs/ directory from numbered files (e.g., 0_PRODUCT_PROFILE.md) to a PROFILE.md convention, establishing a single canonical entry point for each vertical (product, engineering, AI, design).
• Expanded Project Identity: Expanded the chalk.json configuration from 4 fields to a comprehensive, machine-readable project identity, now including details for dev servers, routes, source layout, and test/build commands, along with a new JSON Schema (docs/chalk.schema.json).
• New PR Lifecycle Skills: Introduced five new skills to complete the issue-to-PR workflow: work-issue (for issue setup), commit (for conventional commits), capture-pr-visuals (for visual documentation), create-pr (for PR creation), and validate-chalk (for project context validation).

Changelog

• skills/setup-chalk/SKILL.md
  • Updated skill version to 2.0.0.
  • Modified description to reflect new focus on project identity and structured docs.
  • Updated the produced file structure to use PROFILE.md convention.
  • Added a migration guide for users with the old v1 docs structure.
• skills/setup-docs/SKILL.md
  • Updated skill version to 2.0.0.
  • Modified description to include enriching chalk.json alongside populating PROFILE stubs.
  • Expanded workflow to deeply analyze the codebase and fill missing chalk.json fields (routes, sourceLayout, dev, test) and populate PROFILE docs more comprehensively.
• skills/skills-index.yaml
  • Added new skill entries for capture-pr-visuals, commit, create-pr, validate-chalk, and work-issue.
  • Updated versions for setup-chalk and setup-docs to 2.0.0.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This is a great pull request that significantly improves the structure of the chalk documentation and adds a suite of powerful new skills for the PR lifecycle. The move to a centralized chalk.json as a single source of truth is a solid architectural decision that will make skills more robust and easier to develop. The new PROFILE.md structure and the detailed content generation in setup-chalk and setup-docs are excellent enhancements. The new skills for working with issues, committing, capturing visuals, and creating PRs form a cohesive and very useful workflow. I have one minor suggestion regarding the workflow in capture-pr-visuals to make it more robust. Overall, this is a very impressive and well-executed set of changes.