Skip to content

docs(#7175): document the scribe agent under docs/agents/ - #9222

Merged
waynesun09 merged 5 commits into
fullsend-ai:mainfrom
andrewevansrh:agent/7175-document-scribe-agent
Nov 10, 2026
Merged

waynesun09 merged 5 commits into
fullsend-ai:mainfrom
andrewevansrh:agent/7175-document-scribe-agent

Conversation

@andrewevansrh

@andrewevansrh andrewevansrh commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Documents the scribe agent defined in fullsend-ai/agents by adding docs/agents/scribe.md, adding a row for Scribe to the summary table in docs/agents/README.md, and registering Scribe in the sidebar navigation in docs/.vitepress/config.ts.

Related Issue

Closes #7175

Changes

  • Added docs/agents/scribe.md following the established structure of other agent docs in docs/agents/:
    • Vision: Overview of what the scribe agent does and its value proposition bridging synchronous meetings with autonomous SDLC pipelines.
    • How the agent works: Detailed pipeline stages across host pre-script (PII scrubbing, Drive queries), sandbox (untrusted input defense, recency, substance threshold, public-appropriateness gate, confidence calibration, backlog matching, output formatting), validation loop, and host post-script (deduplication, confidence/public-safety gates, forge/Jira writes).
    • Security model: Untrusted input handling, dedicated GCP service account isolation, host-side PII scrubbing, sandbox network isolation (Vertex AI only), credential isolation, and host-side mutation gates.
    • How it helps: Concrete outcomes and value delivered.
    • Commands: Clarified that slash commands are not accepted; runs on schedule or workflow dispatch.
    • Control labels: Clarified that Scribe does not consume/apply control labels that gate workflow execution; applies meeting-notes (or allowlisted Jira labels) for categorization.
    • Configuration and extension: Dedicated GCP service account setup, environment variables reference table, operating modes (all, comments_only, new_issues_only), Jira Cloud issue creation (fullsend issues create --tracker jira), GitLab host validation, and skills.
    • Source: Link to fullsend-ai/agents harness definition.
  • Updated docs/agents/README.md to add Scribe to the agents summary table.
  • Updated docs/.vitepress/config.ts to include Scribe in the Agents sidebar items.

Testing

  • make lint passes (stage changes first, then run)
  • npm run test passes (Vitest tests)
  • npx vitepress build docs passes without errors
  • Tests added/updated for new or modified logic (Documentation only; verified with lint-docs-links, lint-md-links, and VitePress build)

Checklist

  • PR title follows Conventional Commits (correct type, ! for breaking changes)
  • Commits are signed off (DCO) — human and human-directed agent sessions only
  • I wrote this contribution myself and can explain all changes in it

Add docs/agents/scribe.md to document the scribe agent defined in
fullsend-ai/agents, covering its vision, pipeline behavior, expected
outcomes, commands, control labels, and configuration options (including
dedicated GCP service account setup, Jira issue creation, and operating
modes).

Add scribe to the summary table in docs/agents/README.md and to the
sidebar navigation in docs/.vitepress/config.ts.

Closes fullsend-ai#7175

Signed-off-by: anevans <anevans@redhat.com>
@andrewevansrh
andrewevansrh requested a review from a team as a code owner November 9, 2026 18:20
@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Document the Scribe agent and add it to agent navigation

📝 Documentation 🕐 10-20 Minutes

Grey Divider

AI Description

• Document how Scribe turns meeting notes into backlog comments and issue proposals.
• Explain its security gates, operating modes, credentials, and Jira and GitLab configuration.
• Add Scribe to the agent index and documentation sidebar.
Diagram

graph TD
  Drive[("Google Drive")] --> Pre["Host pre-script"] --> Sandbox["Sandbox analysis"] --> Validate["Schema validation"] --> Post["Host gates"] --> Tracker[("Issue tracker")]
  Context["Repository context"] --> Pre
Loading
High-Level Assessment

A dedicated agent page linked from the existing index and sidebar follows the established documentation structure. Keeping this material only in the agents repository would make it harder to find alongside the other agent guides.

Files changed (3) +174 / -0

Documentation (3) +174 / -0
config.tsAdd Scribe to the Agents sidebar +1/-0

Add Scribe to the Agents sidebar

• Adds a navigation link to the new Scribe guide alongside the existing agent pages.

docs/.vitepress/config.ts

README.mdList Scribe in the agent index +1/-0

List Scribe in the agent index

• Adds a summary row linking to the Scribe guide so readers can discover the agent from the index.

docs/agents/README.md

scribe.mdDocument Scribe behavior, safeguards, and setup +172/-0

Document Scribe behavior, safeguards, and setup

• Introduces a guide to Scribe's meeting-note pipeline, backlog matching, security gates, and expected outcomes. It also documents registration, variables, operating modes, GCP credentials, Jira issue creation, and GitLab host validation.

docs/agents/scribe.md

@qodo-code-review

qodo-code-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Following the Jira setup steps fails on re-registration ✓ Resolved

Resolving commit: 97db912

Resolution reason
Added explanatory text and a fullsend agent remove scribe --fullsend-dir . command before the
local fullsend agent add .fullsend/scribe.yaml --name scribe --fullsend-dir . step in the Jira
section, explaining that duplicate names are refused, so the documented sequence now works.
Description
The Jira section tells operators to run fullsend agent add .fullsend/scribe.yaml --name scribe
after the earlier section already registered scribe with the same name. The CLI reference says
agent add fails when an agent with that name already exists, so an operator who follows the page
in order gets an error and no local override is installed.

2. Docs say Drive key never reaches sandbox ✓ Resolved

Resolving commit: 97db912

Resolution reason
The 'Credential isolation' bullet was rewritten to 'Credential isolation and host-side tokens'. It
now states forge and Jira tokens stay host-side, while the GCP service account key is explicitly
mounted into the sandbox at /tmp/.gcp-credentials.json for Vertex AI and can also access Drive if
granted. It recommends a dedicated service account with minimal scope and restricted sandbox egress,
matching the suggested fix.
Description
The Security model section states that Drive credentials remain on the host and are never injected
into the sandbox, but the agents harness mounts the same GOOGLE_APPLICATION_CREDENTIALS key into the
sandbox at /tmp/.gcp-credentials.json. Operators relying on this page will believe the sandbox
cannot hold the Drive-capable service account key when it can.

3. Variables table drops the Default column ✓ Resolved

Resolving commit: 97db912

Resolution reason
The env-var table was rewritten with a Name | Required | Default | Description layout for both the
main and Jira tables. Defaults (e.g. SCRIBE_LOOKBACK_HOURS=3, SCRIBE_MIN_CONFIDENCE=0.6,
SCRIBE_MODE=all, SCRIBE_JIRA_ISSUE_TYPE=Task, SCRIBE_JIRA_LABELS=meeting-notes) are now in a Default
column. SCRIBE_DRY_RUN is now Required: No with Default true. The dry-run gate prose was reworded to
say it defaults to preview mode, and the Jira table gained a Default column too.
Description
The environment-variable tables in docs/agents/scribe.md use Variable | Required | Description
with no Default column, so defaults such as SCRIBE_LOOKBACK_HOURS (3) and SCRIBE_MIN_CONFIDENCE
(0.6) appear only in prose, and the Jira table has the same gap. The SCRIBE_DRY_RUN row is marked
Required: Yes and the post-script text says it must be set explicitly, yet the reference scheduled
workflow falls back to true (preview mode) when the variable is unset, so operators could think a
missing value fails the run.

View medium (3)
4. Scribe prose runs past the wrap limit ✓ Resolved

Resolving commit: 97db912

Resolution reason
The commit rewraps the scribe.md prose: the pipeline steps (lines 41-61 of the diff) and bullets,
previously several hundred characters per line, are now broken at roughly 80 columns with
continuation lines indented under list items. The Security model, How it helps, and Configuration
paragraphs were rewrapped the same way, matching the suggested fix prompt's rewrap-everything
approach. Tables, headings, and code spans were left as-is.
Description
The new docs/agents/scribe.md leaves pipeline steps and bullets unwrapped, at several hundred
characters per line, far beyond the roughly 80-column limit the contributing guide sets for new
prose. A later one-word edit then marks the whole paragraph as changed, which is the review noise
the guide's line-wrapping rule targets.

5. Agent list grows a static inventory ✓ Resolved

Resolving commit: 97db912

Resolution reason
The commit adds a sentence above the agent table in docs/agents/README.md stating that the full,
current agent inventory is defined and discovered dynamically from the fullsend-ai/agents repository
at runtime (under harness/*.yaml), with a link to that repo. This closely matches the suggested fix
(a sentence above the table pointing to runtime discovery from fullsend-ai/agents with a link). The
table is described as "primary agents shipped by fullsend," so it no longer reads as the full static
inventory.
Description
docs/agents/README.md keeps a hand-maintained table of shipped agents, and this PR adds a Scribe
row while presenting the list as the agent reference. The table has no runtime discovery command or
note that it is partial, so the rule's preferred discovery pattern through fullsend-ai/agents is
not offered to readers.

6. Docs understate Drive access scope ✓ Resolved

Resolving commit: 97db912

Resolution reason
The "At runtime" paragraph was rewritten (diff lines 221-228) to state the pre-script searches
across everything the service account can access, including Shared Drives; the search query is
explicitly described as narrowing matching but not a security boundary; and operators are told to
use a distinctive query and avoid adding the account to unrelated Shared Drives. This mirrors the
suggested fix. The "Use a specific query term to restrict matching" claim is removed.
Description
The At runtime paragraph says the search query restricts matching to intended notes, but the
pre-script searches everything the service account can see, including Shared Drives. Operators
relying on this page could over-share the service account's Drive access.


Informational

7. Search query variable name differs from the workflow's repo variable ✓ Resolved

Resolving commit: 97db912

Resolution reason
Documented in the variables section that SCRIBE_SEARCH_QUERY maps from the repository variable
vars.SCRIBE_GDRIVE_SEARCH_QUERY, and added a SCRIBE_NAME_FILTER row mapped from
vars.SCRIBE_GDRIVE_NAME_FILTER.
Description
The variables table documents SCRIBE_SEARCH_QUERY as the Drive search query setting, but the
reference workflow reads it from the repository variable SCRIBE_GDRIVE_SEARCH_QUERY, and the same
workflow passes an undocumented SCRIBE_NAME_FILTER into the environment. Operators who set the
variable named in the table may find that no query is configured for the scheduled run.

Grey Divider

Context sources
✅ Compliance rules (platform): 96 rules
✅ Skills: 5 invoked
  writing-user-docs
  writing-adrs
  check-patch-coverage
  cutting-releases
  adr-corner
✅ Web pages:
  +2 more
✅ Cross-repo context — repo relationships
  Explored: repo: fullsend-ai/scribe (sha: 0f3eb528) — View relationship
  Explored: repo: fullsend-ai/agents (sha: 82226d2a) — View relationship
Review mode: Auto: 🚀 Fast: Docs-only page plus one sidebar and one table row; localized, low risk.

Grey Divider

Tip of the day
💡 Did you know, you can move or hide resolved findings to focus on what still needs action

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/README.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
- Update environment variable tables to include Default column
- Clarify SCRIBE_DRY_RUN defaults to true (preview mode)
- Document SCRIBE_NAME_FILTER and SCRIBE_SEARCH_QUERY workflow mapping
- Expand Drive search scope guidance regarding Shared Drives
- Accurately describe GCP key mounting in sandbox and credential isolation
- Include agent remove step before local agent add in Jira setup
- Rewrap prose paragraphs and list items to ~80 columns
- Note runtime discovery from fullsend-ai/agents in docs/agents/README.md

Signed-off-by: anevans <anevans@redhat.com>
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

E2E tests are running

Authorization passed for this commit. See the E2E Tests workflow for results.

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 6:34 PM UTC · Completed 6:42 PM UTC

Commit: 97db912 · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.69

@fullsend-ai-review fullsend-ai-review Bot added the risk/moderate PR risk: moderate label Nov 9, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Risk Assessment: moderate (2/5)

Details

Documentation-only PR matching linked issue scope with no protected paths, elevated to moderate risk by high churn, multi-author contention, and regression history on docs/.vitepress/config.ts.

Previous run

Risk Assessment: moderate (2/5)

Details

Documentation-only PR matching linked issue scope with no protected paths, elevated to moderate risk by high churn, multi-author contention, and regression history on docs/.vitepress/config.ts.

Previous run (2)

Risk Assessment: moderate (2/5)

Details

Documentation-only PR matching linked issue scope with no protected paths, elevated to moderate risk by high churn, author contention, and fix history on docs/.vitepress/config.ts.

Previous run (3)

Risk Assessment: moderate (2/5)

Details

Documentation-only PR matching linked issue scope with no protected paths, elevated to moderate risk by high churn, author contention, and fix history on docs/.vitepress/config.ts.

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Review

Findings

Low

  • [api-contract] docs/agents/scribe.md:154 — The documented command fullsend mint add-role scribe cannot run as written: mint add-role always requires --project (no env fallback) and exactly one app-registration mode (--org, or --slug with --pem / --use-existing-pem-secret), so it fails immediately with --project is required.
    Remediation: Show the required flags, e.g. fullsend mint add-role scribe --project "$GCP_PROJECT" --org "$GITHUB_ORG", and link to the mint CLI reference for existing-app alternatives.

Earlier findings

  • docs/agents/scribe.md:244 and docs/agents/scribe.md:255, api-contract — resolved by change (no longer present in the reviewed head).
Previous run

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOlt7InNldmVyaXR5IjoibWVkaXVtIiwiY2F0ZWdvcnkiOiJhcGktY29udHJhY3QiLCJmaWxlIjoiZG9jcy9hZ2VudHMvc2NyaWJlLm1kIiwiaWQiOiJmXzlhNTE3Y2FhNzc3YTEwMmUiLCJsaW5lIjoyNDQsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6ImNvcnJlY3RuZXNzIn0seyJzZXZlcml0eSI6Im1lZGl1bSIsImNhdGVnb3J5IjoiYXBpLWNvbnRyYWN0IiwiZmlsZSI6ImRvY3MvYWdlbnRzL3NjcmliZS5tZCIsImlkIjoiZl8zOTljMmMzMDU1Zjk3MjU1IiwibGluZSI6MjU1LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJjb3JyZWN0bmVzcyJ9XSwiZGlzcG9zaXRpb25zIjpbeyJpZCI6ImZfOWE1MTdjYWE3NzdhMTAyZSIsInN0YXR1cyI6InJlc29sdmVkX2J5X2NoYW5nZSJ9LHsiaWQiOiJmXzM5OWMyYzMwNTVmOTcyNTUiLCJzdGF0dXMiOiJyZXNvbHZlZF9ieV9jaGFuZ2UifV19 -->

Looks good to me

Previous run (2)

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJhcHByb3ZlIiwiZmluZGluZ3MiOlt7InNldmVyaXR5IjoibWVkaXVtIiwiY2F0ZWdvcnkiOiJhcGktY29udHJhY3QiLCJmaWxlIjoiZG9jcy9hZ2VudHMvc2NyaWJlLm1kIiwiaWQiOiJmXzlhNTE3Y2FhNzc3YTEwMmUiLCJsaW5lIjoyNDQsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6ImNvcnJlY3RuZXNzIn0seyJzZXZlcml0eSI6Im1lZGl1bSIsImNhdGVnb3J5IjoiYXBpLWNvbnRyYWN0IiwiZmlsZSI6ImRvY3MvYWdlbnRzL3NjcmliZS5tZCIsImlkIjoiZl8zOTljMmMzMDU1Zjk3MjU1IiwibGluZSI6MjU1LCJhY3Rpb25hYmxlIjp0cnVlLCJkaW1lbnNpb24iOiJjb3JyZWN0bmVzcyJ9XSwiZGlzcG9zaXRpb25zIjpbeyJpZCI6ImZfOWE1MTdjYWE3NzdhMTAyZSIsInN0YXR1cyI6InJlc29sdmVkX2J5X2NoYW5nZSJ9LHsiaWQiOiJmXzM5OWMyYzMwNTVmOTcyNTUiLCJzdGF0dXMiOiJyZXNvbHZlZF9ieV9jaGFuZ2UifV19 -->

Looks good to me

Earlier findings

  • docs/agents/scribe.md:244, api-contract, resolved — agent add/remove commands now run from the repo root with the default .fullsend dir.
  • docs/agents/scribe.md:255, api-contract, resolved — Jira setup now documents tracker.jira config and FULLSEND_JIRA_* credentials.
Previous run (3)

<!-- fullsend:review-findings-v2:eyJ2ZXJzaW9uIjoyLCJhY3Rpb24iOiJyZXF1ZXN0LWNoYW5nZXMiLCJmaW5kaW5ncyI6W3sic2V2ZXJpdHkiOiJtZWRpdW0iLCJjYXRlZ29yeSI6ImFwaS1jb250cmFjdCIsImZpbGUiOiJkb2NzL2FnZW50cy9zY3JpYmUubWQiLCJpZCI6ImZfOWE1MTdjYWE3NzdhMTAyZSIsImxpbmUiOjI0NCwiYWN0aW9uYWJsZSI6dHJ1ZSwiZGltZW5zaW9uIjoiY29ycmVjdG5lc3MifSx7InNldmVyaXR5IjoibWVkaXVtIiwiY2F0ZWdvcnkiOiJhcGktY29udHJhY3QiLCJmaWxlIjoiZG9jcy9hZ2VudHMvc2NyaWJlLm1kIiwiaWQiOiJmXzM5OWMyYzMwNTVmOTcyNTUiLCJsaW5lIjoyNTUsImFjdGlvbmFibGUiOnRydWUsImRpbWVuc2lvbiI6ImNvcnJlY3RuZXNzIn1dfQ== -->

Review

Findings

Medium

  • [api-contract] docs/agents/scribe.md:244 — The documented local-registration commands (fullsend agent remove scribe --fullsend-dir . / fullsend agent add .fullsend/scribe.yaml --name scribe --fullsend-dir .) do not work from any working directory. agent add/agent remove load <fullsend-dir>/config.yaml and resolve a local source relative to --fullsend-dir (runAgentAdd, runAgentRemove, validateLocalPath in internal/cli/agent.go). From the repo root, --fullsend-dir . targets ./config.yaml, not .fullsend/config.yaml. From inside .fullsend, the source resolves to .fullsend/.fullsend/scribe.yaml. The earlier remote-registration example has the same directory problem.
    Remediation: Run the commands from the repository root with --fullsend-dir .fullsend (or omit the flag to use the default), and register the local source as scribe.yaml, relative to that directory.

  • [api-contract] docs/agents/scribe.md:255 — The Jira setup supplies only the legacy JIRA_TOKEN/JIRA_USER_EMAIL/JIRA_BASE_URL variables, but the documented consumer fullsend issues create --tracker jira reads credentials only from FULLSEND_JIRA_* (FULLSEND_JIRA_TOKEN, optional FULLSEND_JIRA_EMAIL, or the FULLSEND_JIRA_CLIENT_ID/FULLSEND_JIRA_CLIENT_SECRET pair). It rejects a legacy-token-only setup and takes the site URL from tracker.jira.base_url rather than JIRA_BASE_URL (internal/cli/tracker_client.go). The external fullsend-ai/agents scripts could not be inspected, so a translation step there is possible but unverified.
    Remediation: Document the current FULLSEND_JIRA_* credentials and the tracker.jira connection settings. Mark any legacy variables as read only by the external scripts. If those scripts translate the variables, state that contract explicitly.


Labels: PR adds user-facing documentation for the scribe agent.


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the component/docs User-facing documentation label Nov 9, 2026
@andrewevansrh

Copy link
Copy Markdown
Contributor Author

Summary of changes in commit 97db9128e

In response to code review feedback on Scribe agent documentation, the following updates were made:

  1. Environment Variables Tables & Defaults:

    • Updated both the general and Jira-specific variable tables to use the standard Name | Required | Default | Description column layout.
    • Populated explicit defaults for all documented variables.
    • Updated SCRIBE_DRY_RUN to reflect Required: No and Default: true (preview mode), and aligned the post-script dry-run gate prose accordingly.
  2. Workflow Repository Variable Mapping:

    • Documented that SCRIBE_SEARCH_QUERY is mapped from repository variable vars.SCRIBE_GDRIVE_SEARCH_QUERY in reference workflows.
    • Added SCRIBE_NAME_FILTER (mapped from vars.SCRIBE_GDRIVE_NAME_FILTER) to the variables table.
  3. Line Wrapping:

    • Rewrapped all prose paragraphs and bullet lists in docs/agents/scribe.md to ~80 columns, indenting continuation lines for list items per docs/contributing/documentation.md.
  4. Agent Inventory Discovery:

    • Added explanatory text above the agent summary table in docs/agents/README.md clarifying that the table lists primary documented agents, while the complete, active inventory is discovered dynamically at runtime from fullsend-ai/agents.
  5. Local Harness Registration in Jira Setup:

    • Added fullsend agent remove scribe --fullsend-dir . prior to the fullsend agent add command for the local Jira harness override to avoid duplicate agent registration errors.
  6. Credential Scope & Isolation:

    • Clarified that forge tokens (GH_TOKEN, GITLAB_TOKEN) and Jira tokens remain strictly host-side, while the GCP service account key (GOOGLE_APPLICATION_CREDENTIALS) is mounted into the sandbox at /tmp/.gcp-credentials.json for Vertex AI inference (with sandbox network egress isolated to Vertex AI).
  7. Google Drive Access Boundary:

    • Clarified that SCRIBE_SEARCH_QUERY narrows document matching but is not a security boundary, as the service account can access all Drive files and Shared Drives it has been added to. Advised using distinctive query terms and avoiding adding the service account to unrelated Shared Drives.

Note: Generated with assistance from Gemini

@codecov

codecov Bot commented Nov 9, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Site preview

Preview: https://d54587ff-site.fullsend-ai.workers.dev

Commit: d52749d470511f27c4626382b5bced6d45212c1d

…tials for scribe

- Update agent add/remove commands to run from repo root with default .fullsend
- Register local harness override using scribe.yaml relative to fullsend dir
- Document tracker.jira config and FULLSEND_JIRA_* env credentials for CLI
- Clarify legacy JIRA_* variables are consumed only by external scripts

Signed-off-by: anevans <anevans@redhat.com>
@andrewevansrh

Copy link
Copy Markdown
Contributor Author

Summary of review feedback addressed in commit 2b542ee7c

In response to review feedback from fullsend-ai-review, the following corrections were made in docs/agents/scribe.md:

  1. Agent Registration Directory Semantics:

    • Updated the general agent registration example to run from the repository root using the default --fullsend-dir .fullsend, removing the incorrect --fullsend-dir . flag which targeted the wrong config location.
    • Updated the local harness override command under Jira setup to reference scribe.yaml relative to .fullsend/ (matching internal/cli/agent.go resolution and validation logic) and use the default --fullsend-dir.
  2. Jira Tracker Configuration and Credentials:

    • Documented the repository connection configuration under tracker.jira in .fullsend/config.yaml (base_url, project, and optional api_url).
    • Documented the current FULLSEND_JIRA_* credentials required by fullsend issues create --tracker jira (FULLSEND_JIRA_TOKEN with optional FULLSEND_JIRA_EMAIL, or OAuth credentials FULLSEND_JIRA_CLIENT_ID and FULLSEND_JIRA_CLIENT_SECRET).
    • Differentiated legacy variables (JIRA_BASE_URL, JIRA_TOKEN, JIRA_USER_EMAIL), marking them as read only by external harness scripts for backlog querying if those scripts do not translate credentials, while explicitly clarifying that the CLI strictly enforces FULLSEND_JIRA_* and tracker.jira.

Commits Created & Pushed

  • 2b542ee7c docs(#7175): correct registration commands and jira credentials for scribe on branch agent/7175-document-scribe-agent

Verification

  • Staged changes and ran make lint, passing all linters, formatting, markdown link verification, and security checks.
  • Verified line lengths and indentation across all updated paragraphs and list items against project documentation standards (~80 columns).

Note: Generated with assistance from Gemini

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:05 PM UTC · Completed 7:15 PM UTC

Commit: 2b542ee · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.54

@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 9, 2026 19:15

Superseded by updated review

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 9, 2026
@andrewevansrh andrewevansrh self-assigned this Nov 9, 2026

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review-only pass: five inline findings on docs/agents/scribe.md (one HIGH, four MEDIUM). Most come from comparing the page with the scribe harness and scripts in fullsend-ai/agents and with how fullsend run validates harness env.

Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
Comment thread docs/agents/scribe.md Resolved
…d credentials

- Document JIRA_* credentials used by external scribe scripts and
  translated to CLI
- Require SCRIBE_DRY_RUN explicitly and explain post-script preview
  behavior
- Note that all harness variables must exist in runner environment
- State sandbox egress allows configured inference providers (Vertex AI
  and OpenAI)
- Document scribe prerequisites, dogfood role, and link example workflows
- Clarify built-in agent resolution vs opt-in scribe harness in README

Signed-off-by: anevans <anevans@redhat.com>
@andrewevansrh

Copy link
Copy Markdown
Contributor Author

Summary of review feedback addressed in commit b1e692c0f

In response to code review feedback from @waynesun09 on PR #9222, the following updates were made:

  1. Jira Credential Setup & Script Contract:

    • Removed FULLSEND_JIRA_* and OAuth credential rows from the Jira variables table and harness snippet in docs/agents/scribe.md.
    • Documented JIRA_BASE_URL and JIRA_TOKEN as required for Jira mode, and JIRA_USER_EMAIL as optional (for Basic auth; omitting uses Bearer auth), explaining that external harness scripts translate and pass these credentials to fullsend issues create as FULLSEND_JIRA_*.
    • Removed FULLSEND_DIR from the harness snippet, as it is set automatically by runner preflight.
    • Linked Jira configuration guidance in fullsend-ai/agents docs/scribe.md.
  2. SCRIBE_DRY_RUN Safety Gate & Default Behavior:

    • Marked SCRIBE_DRY_RUN as Required: Yes in the variables table.
    • Updated the description and post-script safety gate prose to clarify that the variable must be explicitly defined (the script halts with an error if unset), that false enables live writes, and that any other value previews actions in logs without mutations. Noted that the reference dogfood workflow in fullsend-ai/.fullsend defaults to previewing by passing true.
  3. Harness Environment Variable Validation:

    • Added explanatory prose preceding the variables table clarifying that because harness/scribe.yaml references these variables in env.runner and env.sandbox, every referenced variable must exist in the runner environment (can be set to empty strings "" when using defaults), as fullsend run validates harness environment variables and fails if any variable is omitted.
    • Clarified that documented defaults apply when the variable is empty.
  4. Sandbox Network Isolation & Credential Risk Scope:

    • Updated the network isolation description in the security model to state that outbound network policy permits only configured inference providers (Vertex AI and OpenAI in the shipped harness), while forge and Drive APIs are blocked.
    • Rephrased the credential isolation note to reflect risk reduction rather than an absolute guarantee against exfiltration.
  5. Prerequisites, Dogfood Role Wiring, and Agent Discovery:

    • Added a "Prerequisites and workflow setup" section in docs/agents/scribe.md explaining that Scribe is an opt-in agent and mint-only dogfood role (fullsend mint add-role scribe) not valid under roles:, requiring users to supply their own scheduled/dispatch workflow. Linked the reference workflow in fullsend-ai/.fullsend and the guide in fullsend-ai/agents.
    • Updated docs/agents/README.md to clarify that built-in agents resolve through repository config or the agents repository fallback, whereas additional agents such as Scribe are opt-in and must be added with fullsend agent add. Labeled Scribe as (opt-in) in the agent summary table.

Commits Created & Pushed

  • b1e692c0f docs(#7175): address review feedback on scribe workflow and credentials on branch agent/7175-document-scribe-agent

Verification

  • Staged all changes and ran make lint, passing all pre-commit hooks (markdown link checker lint markdown links, documentation link scope lint docs link scope, semgrep security audit, secret detection, formatting, and gitlint).
  • Verified markdown line lengths and list continuation indentation across all updated files against project documentation standards (~80 columns).

Note: Generated with assistance from Gemini

@fullsend-ai-review

fullsend-ai-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 7:42 PM UTC · Completed 7:49 PM UTC

Commit: b1e692c · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.15

@fullsend-ai-review fullsend-ai-review Bot removed the ready-for-merge All reviewers approved — ready to merge label Nov 9, 2026
@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 9, 2026 19:49

Superseded by updated review

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 9, 2026
@ralphbean ralphbean added the ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) label Nov 9, 2026
@ralphbean

Copy link
Copy Markdown
Member

After #9229 is merged, please rebase on main to pick up that ty fix (to unblock CI here).

@andrewevansrh andrewevansrh added ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) and removed ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) labels Nov 10, 2026
@github-actions github-actions Bot removed the ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) label Nov 10, 2026
@fullsend-ai-review

fullsend-ai-review Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 1:16 PM UTC · Completed 1:25 PM UTC

Commit: d52749d · View workflow run →

Runtime: pi · Model: sonnet → claude-sonnet-5-5 · Effort: high · Cost: $1.72

@fullsend-ai-review fullsend-ai-review Bot removed the ready-for-merge All reviewers approved — ready to merge label Nov 10, 2026
Comment thread docs/agents/scribe.md Resolved
@fullsend-ai-review
fullsend-ai-review Bot dismissed their stale review November 10, 2026 13:25

Superseded by updated review

@fullsend-ai-review fullsend-ai-review Bot added the ready-for-merge All reviewers approved — ready to merge label Nov 10, 2026
@ralphbean ralphbean added the ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) label Nov 10, 2026

@ralphbean ralphbean left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@ralphbean
ralphbean enabled auto-merge November 10, 2026 13:44
@ralphbean ralphbean self-assigned this Nov 10, 2026

@waynesun09 waynesun09 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. All five review findings are fixed in b1e692c. I checked the Jira credential flow against the scribe scripts in fullsend-ai/agents: JIRA_TOKEN and JIRA_USER_EMAIL are passed to the CLI as FULLSEND_JIRA_*, with connection settings from tracker.jira.

@waynesun09
waynesun09 added this pull request to the merge queue Nov 10, 2026
Merged via the queue into fullsend-ai:main with commit 7449efd Nov 10, 2026
104 checks passed

This branch was successfully deployed

1 active and 1 inactive deployments
dev — d52749d4 Deployed Nov 10, 2026 by ralphbean via run / behaviour #6544
site-preview — d52749d4 Deployed Nov 10, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/docs User-facing documentation ok-to-test Allow e2e CI to run after maintainer review (must be re-applied after each push) ready-for-merge All reviewers approved — ready to merge risk/moderate PR risk: moderate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the scribe agent under docs/agents/

3 participants