sharing-pr-agent-artifacts

Sharing PR agent artifacts

Uploads intermediate files (implementation plans, specs, learnings, explorations, architecture diagrams) to streamlit.wiki so they can be linked in PR descriptions and comments. Use this for agent-generated artifacts that are useful for reviewers but don't belong in the main repo.

Important: The wiki repo uses master as its default branch. Always push to master, never create other branches.

Follow the wiki guidelines: After cloning/updating the wiki repo, read and follow agent-wiki/AGENTS.md for the authoritative rules on what to upload and how to organize files.

Public URL pattern:

https://issues.streamlit.app/agent_wiki_explorer?file=<relative-path>

Example: https://issues.streamlit.app/agent_wiki_explorer?file=pull-requests/12345/implementation-plan.md

Prerequisites

• A PR must exist for the current branch

Workflow

1. Get PR number

gh pr view --json number --jq '.number'

If no PR exists, stop and inform the user.

2. Set up wiki repo

Check if the wiki is already cloned:

if [ -d "agent-wiki/.git" ]; then
  # Use subshell to avoid directory navigation issues if pull fails
  (cd agent-wiki && git checkout master && git pull origin master)
else
  git clone https://github.com/streamlit/streamlit.wiki.git agent-wiki
fi

3. Create PR directory

mkdir -p agent-wiki/pull-requests/<pr-number>

4. Discover and copy files

Common locations (check these first):

• work-tmp/ — temporary working files, drafts, exploration notes
• specs/ — untracked product/tech specs created for this PR

What to include:

• Specs, plans, design docs (.md)
• Implementation notes and decisions
• Architecture diagrams (.png, .svg)
• Research findings and explorations

Always exclude:

Warning: The wiki is a public repo. Never upload confidential information, internal sensitive discussions, or anything that shouldn't be publicly visible. Since Streamlit is open-source, almost all tech and product related planning documents are fine to share publicly.

• Files already tracked in the main repo (use git ls-files to check)
• Credentials, secrets, tokens, API keys (.env, *credentials*, *secret*, *token*, *api_key*)
• Confidential or internal-only information
• Test-related artifacts
• Debug logs and temporary output
• Build artifacts
• Large binary files (>10MB)
• IDE/editor files
• Files unrelated to the current PR

Copy selected files:

cp <file> agent-wiki/pull-requests/<pr-number>/

5. Commit and push

# Use subshell to avoid directory navigation issues
(
  cd agent-wiki
  git checkout master
  git add pull-requests/
  git commit -m "Add artifacts for PR #<pr-number>"
  git pull --rebase origin master
  git push origin master
)

If push fails due to conflicts:

1. Run git pull --rebase origin master
2. Resolve conflicts manually
3. Run git rebase --continue
4. Push again

Never use --force.

6. Comment on PR

If new files were added, post a summary comment to the PR:

gh pr comment <pr-number> --body "$(cat <<'EOF'
### Added Agent Docs

- [implementation-plan.md](https://issues.streamlit.app/agent_wiki_explorer?file=pull-requests/<pr-number>/implementation-plan.md): Main technical implementation plan
- [exploration.md](https://issues.streamlit.app/agent_wiki_explorer?file=pull-requests/<pr-number>/exploration.md): Initial research and design exploration
EOF
)"

Include only top-level documents relevant to reviewers. Assets embedded in those documents (e.g., images) don't need separate entries.

PR-independent reference files

For documents useful beyond a single PR (deep dives, architecture explorations, research findings), use the references/ directory instead of pull-requests/.

When to use references

• Codebase explorations not tied to a specific change
• Architecture deep dives useful for future work
• Research findings that inform multiple features
• Decision logs with broader applicability

Workflow

# Create file with date prefix
mkdir -p agent-wiki/references
cp <file> agent-wiki/references/YYYY-MM-DD-<description>.md

Example: 2024-03-15-widget-state-deep-dive.md

Use the same commit/push workflow as PR artifacts (step 5), substituting references/ for pull-requests/ in both the git add command and the commit message (e.g., "Add reference: YYYY-MM-DD-<description>").

Public URL: https://issues.streamlit.app/agent_wiki_explorer?file=references/YYYY-MM-DD-<description>.md

Notes

• The agent-wiki/ directory is gitignored and persists across sessions
• Always push to master — never create feature branches or use --force
• This is a public repo — never push sensitive information
• Only upload files directly relevant to the current PR or general reference materials