You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: agents/interview-conductor.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,7 +67,7 @@ The loop works as follows — repeat until `action` is `interview_complete` or t
67
67
## Session Management
68
68
69
69
- When starting a NEW session: the command has already created the session directory and provided you the session_id and session_dir path. Load state.json and begin the loop.
70
-
-**Data directory**: All sessions and profiles are stored under `$CLAUDE_PLUGIN_DATA` when set, otherwise under `~/.human-voice/`. When looking for existing sessions or profiles, always check `~/.human-voice/` as the canonical fallback location.
70
+
-**Data directory**: All sessions and profiles are stored under `~/.human-voice/`. This is the single canonical location — no env vars redirect it. Always look for existing sessions and profiles there.
71
71
- When RESUMING: load state.json, recap progress conversationally ("Welcome back — you're in Section X of Y, about Z minutes remaining"), then enter the loop at step 1.
72
72
- After every user response, save session state atomically to `state.json` within the session directory.
73
73
- The state file tracks: current module, current question index, all collected responses, branching decisions, format streak count, quality flags, and timing data.
Copy file name to clipboardExpand all lines: agents/profile-synthesizer.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -93,11 +93,11 @@ print(f'Profile published as {slug} -> {path}')
93
93
"
94
94
```
95
95
96
-
This stores the profile under `$CLAUDE_PLUGIN_DATA/profiles/{slug}/` and activates it, which copies to the top-level well-known locations:
97
-
-`$CLAUDE_PLUGIN_DATA/profile.json` — full voice profile (read by hooks and agents)
98
-
-`$CLAUDE_PLUGIN_DATA/voice-prompt.txt` — compact injection text for LLM system prompts
96
+
This stores the profile under `~/.human-voice/profiles/{slug}/` and activates it, which copies to the top-level well-known locations:
97
+
-`~/.human-voice/profile.json` — full voice profile (read by hooks and agents)
98
+
-`~/.human-voice/voice-prompt.txt` — compact injection text for LLM system prompts
99
99
100
-
**IMPORTANT**: When `$CLAUDE_PLUGIN_DATA` is not set, the data directory defaults to `~/.human-voice`. All profiles, sessions, and config live under `~/.human-voice/` in standalone/development mode. When looking for existing profiles, always check `~/.human-voice/profiles/` and `~/.human-voice/profile.json` as the canonical fallback locations.
100
+
**IMPORTANT**: All profiles, sessions, and config live under `~/.human-voice/`. This is the single canonical location — no env vars redirect it. Always look for existing profiles at `~/.human-voice/profiles/` and the active profile at `~/.human-voice/profile.json`.
101
101
102
102
The session is also marked as `complete` automatically.
If `$ARGUMENTS` is empty, run with defaults (active profile, install into cwd, merge mode).
24
+
25
+
## Steps
26
+
27
+
**Important**: always invoke the CLI via its absolute path at `${CLAUDE_PLUGIN_ROOT}/bin/voice-copilot-install`. The default `--target=.` resolves against the user's current working directory (the project they're standing in), which is what you want. Do NOT `cd` into the plugin root first — that would make `--target=.` resolve to the plugin itself.
28
+
29
+
1.**Run**: `"${CLAUDE_PLUGIN_ROOT}/bin/voice-copilot-install" $ARGUMENTS`. Surface the list of written/skipped files. If the user passed `--dry-run`, the CLI will print intended writes and touch nothing — do not follow up with a real install unless they ask.
30
+
31
+
2.**Report**: Summarise what was written and point the user at `.github/copilot-instructions.md` as the entry point. If a workflow was written, remind them to commit and push so Copilot code review picks it up on the next PR.
32
+
33
+
## What gets written
34
+
35
+
-`.github/copilot-instructions.md` — repo-wide, loaded by Copilot automatically on GitHub.
36
+
-`AGENTS.md` at repo root — coding-agent instructions.
37
+
-`.github/instructions/human-voice-<slug>.instructions.md` — path-scoped (one per profile; `applyTo` glob drives routing).
-`.github/workflows/voice-review.yml` — PR workflow that runs validators on changed prose and comments findings.
43
+
44
+
Repo-wide instructions and AGENTS.md are written inside `<!-- human-voice:start -->` / `<!-- human-voice:end -->` markers, so re-runs are idempotent and never clobber user-added content outside the block.
45
+
46
+
## Notes
47
+
48
+
- Profile data is redacted by default before embedding (drops `metadata` and `known_gaps`, trims `calibration` to its summary). Pass `--no-redact` only for private repos.
49
+
- The workflow triggers only on pull requests touching `docs/**`, `README*`, `CHANGELOG*`, `CONTRIBUTING*`, and `**/*.{md,mdx}`.
50
+
- For multi-profile installs, provide a `--route` spec mapping globs to slugs. The default profile applies to anything not matched by an explicit glob.
2.**Load profile**: Read `${CLAUDE_PLUGIN_DATA}/profile.json` for current dimension scores (`${CLAUDE_PLUGIN_DATA}` defaults to `~/.human-voice` when not set). Extract the score for each dimension from the `dimensions` object. Do not use hardcoded values; every user's profile is different.
22
+
2.**Load profile**: Read `~/.human-voice/profile.json` for current dimension scores. Extract the score for each dimension from the `dimensions` object. Do not use hardcoded values; every user's profile is different.
23
23
24
24
3.**Compare**: For each observation, compare against the dimension scores loaded from the profile in step 2. Cover all gold standard dimensions (formality, emotional_tone, personality, complexity, audience_awareness, authority, narrativity, humor) and all gap dimensions that have scores. Also compare mechanics observations (contractions, Oxford comma, punctuation style) against the `mechanics` section of the profile.
Copy file name to clipboardExpand all lines: commands/voice-interview.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ Start a new voice elicitation interview session.
11
11
12
12
## Procedure
13
13
14
-
1.**Create session**: Run `bin/voice-session create` to generate a new session. This creates `${CLAUDE_PLUGIN_DATA}/sessions/{session_id}/` with `state.json` and `responses.jsonl`. Capture the session_id and session_dir path from the output.
14
+
1.**Create session**: Run `bin/voice-session create` to generate a new session. This creates `~/.human-voice/sessions/{session_id}/` with `state.json` and `responses.jsonl`. Capture the session_id and session_dir path from the output.
15
15
16
16
2.**Load question bank**: Verify question bank modules exist in `question-bank/modules/`.
Interactive configuration wizard. Creates `${CLAUDE_PLUGIN_DATA}/config.json` — the unified config for both AI pattern detection and voice elicitation.
10
+
Interactive configuration wizard. Creates `~/.human-voice/config.json` — the unified config for both AI pattern detection and voice elicitation.
11
11
12
12
## Process
13
13
14
-
1.**Check for existing config**: Read `${CLAUDE_PLUGIN_DATA}/config.json` if it exists. Ask: "Configuration exists. Update or replace?"
14
+
1.**Check for existing config**: Read `~/.human-voice/config.json` if it exists. Ask: "Configuration exists. Update or replace?"
15
15
16
16
2.**Detect project structure**: Scan for content directories (`docs/`, `_posts/`, `content/`, `_docs/`), markdown files, and static site generators.
Copy file name to clipboardExpand all lines: docs/guides/copilot-integration.md
+72-3Lines changed: 72 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,17 +6,86 @@ diataxis_goal: Export voice profiles to a repository for use by GitHub Copilot a
6
6
7
7
# Integrating with GitHub Copilot
8
8
9
-
This guide covers how to export voice profiles to a repository so GitHub Copilot applies them automatically during content generation and review.
9
+
This guide covers how to install voice profiles into a project so GitHub Copilot (code review, coding agent, chat) applies them automatically.
10
+
11
+
Two commands are available:
12
+
13
+
-**`voice-copilot-install`** (recommended) — writes the full Copilot surface: `copilot-instructions.md`, path-scoped `instructions/*.instructions.md`, reusable `prompts/*.prompt.md`, custom `agents/*.agent.md`, root `AGENTS.md`, redacted profile artefacts under `.github/human-voice/`, and a PR review workflow. Idempotent.
14
+
-**`voice-profiles install`** (minimal) — writes only a single `.github/copilot-instructions.md`. Retained for users who want the smallest footprint.
10
15
11
16
## Prerequisites
12
17
13
18
- At least one voice profile stored in the registry (from an interview, design, or template)
14
19
- The human-voice plugin installed
15
20
- GitHub Copilot enabled on the target repository
16
21
17
-
## Install profiles to a repository
22
+
## Full Copilot install (recommended)
23
+
24
+
Run the slash command from the target project root, or invoke the CLI directly:
25
+
26
+
```
27
+
/human-voice:voice-copilot-install
28
+
```
29
+
30
+
```bash
31
+
bin/voice-copilot-install --target /path/to/repo
32
+
```
33
+
34
+
With no flags, this installs the currently-active profile into the cwd using merge mode. The command is idempotent — re-running replaces only the content between `<!-- human-voice:start -->` / `<!-- human-voice:end -->` markers; anything you added outside those markers is preserved.
35
+
36
+
### What it writes
37
+
38
+
| Path | Role |
39
+
|---|---|
40
+
|`.github/copilot-instructions.md`| Repo-wide instructions loaded automatically by Copilot. |
41
+
|`AGENTS.md`| Root-level instructions for Copilot coding agent. |
42
+
|`.github/instructions/human-voice-<slug>.instructions.md`| Path-scoped rules; the `applyTo` frontmatter glob drives routing. |
43
+
|`.github/prompts/voice-review.prompt.md`|`/voice-review` slash command in Copilot Chat. |
44
+
|`.github/prompts/voice-fix.prompt.md`|`/voice-fix` — rewrite a selection in-voice. |
45
+
|`.github/prompts/voice-draft.prompt.md`|`/voice-draft` — new content in-voice. |
46
+
|`.github/agents/human-voice-<slug>.agent.md`| Copilot custom agents (one per profile). |
47
+
|`.github/human-voice/<slug>/profile.json`| Redacted profile (metadata and raw calibration stripped). |
Each profile gets its own `instructions/*.instructions.md` with a distinct `applyTo` glob. The default profile covers anything not matched by an explicit glob.
65
+
66
+
### Privacy
67
+
68
+
By default, the installer redacts the embedded `profile.json`: it drops `metadata` (session ID, notes), drops `known_gaps`, and trims `calibration` to its summary. The retained fields (`dimensions`, `mechanics`, `distinctive_features`, `voice_aspirations`, `identity_summary`, `calibration.summary`) are the signals Copilot needs to emulate voice. Pass `--no-redact` only for private repos where the full profile is acceptable.
69
+
70
+
### Dry run
71
+
72
+
```bash
73
+
bin/voice-copilot-install --dry-run
74
+
```
75
+
76
+
Prints the list of files that would be written, with byte sizes. Touches nothing.
-`--overwrite force` — overwrite the entire target file.
82
+
-`--overwrite error` — fail if any target exists.
83
+
84
+
Non-markered files (instructions, prompts, agents, workflow, embedded artefacts) are overwritten in `force` mode and skipped in `error` mode.
85
+
86
+
## Minimal install (legacy)
18
87
19
-
Use the `voice-profiles install` command to export one or more profiles into a repository. This generates a single `.github/copilot-instructions.md` file containing all specified profiles with routing logic.
88
+
Use the original `voice-profiles install` command to export one or more profiles into a repository. This generates a single `.github/copilot-instructions.md` file containing all specified profiles with routing logic.
0 commit comments