[PAW About UX] Ground PAW onboarding in project docs #290
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -15,7 +15,7 @@ Serve as the workflow navigator and historian. Diagnose current workflow state, | |
|
|
||
| - Diagnose current workflow state from artifacts and git | ||
| - Recommend appropriate next steps | ||
| - Explain what PAW is, how the workflow works, and how to get started | ||
| - List active work items across workspace | ||
| - List available workflow presets (built-in and user-defined) | ||
| - Post status updates to Issues/PRs (on explicit request) | ||
|
|
@@ -157,6 +157,18 @@ When asked "What presets are available?" or "List presets": | |
|
|
||
| ## Help Mode | ||
|
|
||
| For "What is PAW?", "What does PAW stand for?", or similar onboarding questions: | ||
| - Use the exact name **Phased Agent Workflow**. Never invent an acronym expansion. | ||
| - Ground the answer in repository docs before replying: `README.md` (`## What is PAW?`), `docs/index.md`, `docs/guide/index.md`, and `docs/guide/cli-installation.md`. | ||
| - Explain briefly: | ||
| - PAW enables **Context-Driven Development**: agents build understanding through durable artifacts (specs, research, plans) before writing code. | ||
| - PAW supports two workflows: implementation and review. | ||
| - Workflow **stages** are top-level milestones; implementation **phases** are subdivisions inside `ImplementationPlan.md`. | ||
| - If the user also asks how to get started, tailor the answer by platform: | ||
|
Owner
Author
There was a problem hiding this comment. Use the {{vscode}} and {{cli}} templates to modify prompts based on target platform, instead of mentioning target platforms in prompts. @copilot please fix. |
||
| - **GitHub Copilot CLI**: install via `copilot plugin install lossyrob/phased-agent-workflow` or `npx @paw-workflow/cli install copilot`, then start with `copilot --agent PAW` (or `/agent PAW` in an existing session). | ||
| - **VS Code**: install the extension, then run `PAW: New PAW Workflow`. | ||
| - Prefer concise, sourced onboarding language over improvisation. | ||
|
|
||
| When asked "What does <stage> do?", provide: | ||
| 1. Purpose of the stage | ||
| 2. Required inputs/artifacts | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| import { describe, it } from "node:test"; | ||
| import assert from "node:assert"; | ||
| import { readFile } from "fs/promises"; | ||
| import { resolve } from "path"; | ||
| import { fileURLToPath } from "url"; | ||
|
|
||
| const __dirname = fileURLToPath(new URL(".", import.meta.url)); | ||
| const REPO_ROOT = resolve(__dirname, "../../../../"); | ||
|
|
||
| describe("paw-status about-paw guidance", () => { | ||
| it("grounds about-paw answers in the correct name, concepts, and source docs", async () => { | ||
| const content = await readFile(resolve(REPO_ROOT, "skills/paw-status/SKILL.md"), "utf-8"); | ||
|
|
||
| assert.match(content, /Use the exact name \*\*Phased Agent Workflow\*\*/); | ||
| assert.match(content, /Never invent an acronym expansion/i); | ||
| assert.match(content, /Context-Driven Development/); | ||
| assert.match(content, /README\.md.*docs\/index\.md.*docs\/guide\/index\.md.*docs\/guide\/cli-installation\.md/s); | ||
| assert.match(content, /GitHub Copilot CLI/); | ||
| assert.match(content, /VS Code/); | ||
| }); | ||
|
|
||
| it("routes about/onboarding requests to paw-status", async () => { | ||
| const agent = await readFile(resolve(REPO_ROOT, "agents/PAW.agent.md"), "utf-8"); | ||
| const reference = await readFile(resolve(REPO_ROOT, "docs/reference/agents.md"), "utf-8"); | ||
|
|
||
| assert.match(agent, /About PAW, onboarding, install, or "how do I get started\?" questions → `paw-status`/); | ||
| assert.match(reference, /"What is PAW\?" or "How do I get started\?" → `paw-status` skill/); | ||
| }); | ||
|
|
||
| it("keeps the top-level docs aligned on cross-platform onboarding", async () => { | ||
| const docsIndex = await readFile(resolve(REPO_ROOT, "docs/index.md"), "utf-8"); | ||
| const guideIndex = await readFile(resolve(REPO_ROOT, "docs/guide/index.md"), "utf-8"); | ||
|
|
||
| assert.match(docsIndex, /\*\*GitHub Copilot CLI\*\* and \*\*VS Code\*\*/); | ||
| assert.match(docsIndex, /CLI installation/); | ||
| assert.match(guideIndex, /CLI Installation/); | ||
| assert.match(guideIndex, /VS Code extension/); | ||
| }); | ||
| }); |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Final skill installation target won't have access to the docs, so this will either need to be linked to the documentation website or replaced with in-lined context. @copilot please fix.