artefact-retrieval

SKILL_artefact-retrieval

Overview

IDE-agnostic pattern for retrieving valuable artefacts (plans, analyses, validation reports, research notes) that AI coding assistants generate outside the project tree, and importing them into the project's docs/artefacts/ taxonomy for permanent retention and cross-session reuse.

Host Environments

This skill works identically whether the agent is invoked from:

• Claude Code (CLI, IDE extension, or Desktop app)
• Antigravity (Gemini brain workspace)
• Cursor (Plan Mode, Composer, or Agent)
• Any combination — same project, multiple assistants across sessions

The retrieval logic is source-agnostic: each IDE/assistant writes its artefacts to a known location outside the repo, and this skill catalogues those locations so any agent can sweep them into the project artefact tree.

⚠️ Claude Code auto-memory: consult, don't copy

~/.claude/projects/*/memory/ is personal memory, not an artefact store — memory files stay where they are and are never copied into docs/artefacts/.

But memory informs retrieval. Before sweeping IDE locations, skim:

• MEMORY.md and any project_*.md entries for the active project — they often name current initiatives, IDEA numbers, modules, stakeholders, and deadlines. Use these to seed PROJECT_KEYWORDS for the discovery sweep (§2) and the unsaved-artefacts audit (§5).
• user_*.md / feedback_*.md for signals about which assistant (Cursor / Antigravity / Claude Code) the user has been using recently — narrows where to look first.

The same consult-don't-copy rule applies to ~/.claude/CLAUDE.md and private user config. ~/.gemini/ / ~/.cursor/ config, credentials, and session metadata remain fully off limits — only generated work product (plans, analyses, walkthroughs) from those workspaces is a retrieval candidate.

When to Use

• 🆕 Starting a new project and looking for validated knowledge from prior work
• 🔍 Researching proven patterns before implementing a solution
• ✅ Validating assumptions against documented findings
• 🧹 Periodic sweep for completed plans and analyses that still live outside the repo
• 🔄 Ensuring consistency across agents (Claude Code / Antigravity / Cursor all see the same canonical knowledge)

Artefact Sources (Complete Reference)

Source	Location	Format
In-repo agent outputs	docs/artefacts/by-agent/	Markdown
In-repo research / validations	docs/artefacts/by-type/	Markdown
In-repo topic cross-refs	docs/artefacts/by-topic/	Symlinks
Cursor plans	~/.cursor/plans/*.plan.md	YAML frontmatter + Markdown
Cursor agent transcripts	~/.cursor/projects/<project>/agent-transcripts/	JSONL
Antigravity/Gemini artefacts	~/.gemini/antigravity/brain/<id>/artifacts/	Markdown
Antigravity/Gemini transcripts	~/.gemini/antigravity/brain/<id>/.system_generated/logs/overview.txt	Text
Claude Code transcripts	~/.claude/projects/<project-slug>/*.jsonl	JSONL (session logs)
Temp scratch	/tmp/*.md, /tmp/artefacts/	Markdown

Excluded from copying (consult-only or fully off-limits)

• 📖 ~/.claude/projects/*/memory/ — personal agent memory; consult project-type entries for keywords and scope, but never copy into docs/artefacts/
• ❌ Any .env, credentials, session tokens — fully off-limits
• ❌ Raw transcripts — search them for artefact references, but don't copy wholesale

Pattern

1. Pick the source

Figure out which assistant generated the artefact. If unsure, sweep all known locations (§2).

2. Discovery — list and filter

# Cursor plans — newest first
ls -lt ~/.cursor/plans/*.plan.md 2>/dev/null

# Antigravity/Gemini brains — newest first
ls -lt ~/.gemini/antigravity/brain/ 2>/dev/null

# Show names + status at a glance for Cursor plans
for f in ~/.cursor/plans/*.plan.md; do
    name=$(grep "^name:" "$f" | head -1 | sed 's/name: //')
    echo "$f → $name"
done

# Find plans/artefacts matching a project keyword across all sources
KEYWORDS="myproject|IDEA-|ai_service|dashboard"
grep -rlE "$KEYWORDS" \
    ~/.cursor/plans/ \
    ~/.gemini/antigravity/brain/ \
    2>/dev/null

3. Assess relevance before copying

Open the artefact. Ask:

• Is the work complete (Cursor: all todos status: completed; Antigravity: final draft)?
• Does it document a non-trivial architectural decision or reusable pattern?
• Could it inform future work — not just describe what the agent did?
• Does it match the current project context (framework, stack, production state)?

Low-value ephemera (single-file bug fixes, debug logs, one-shot refactors) usually doesn't need saving — the git history already captures the change.

4. Import into the project taxonomy

Ensure the taxonomy exists (first-time setup):

mkdir -p docs/artefacts/by-type/{plans,analyses,validations,research,reports}
mkdir -p docs/artefacts/by-topic/{architecture,deployment,security,frontend,backend}
mkdir -p docs/artefacts/by-agent

Copy the artefact and symlink into topic cross-refs:

# Example: Cursor plan for text file preview feature
cp ~/.cursor/plans/idea-057_text_file_preview_52778d48.plan.md \
   docs/artefacts/by-type/plans/IDEA-057-text-file-preview.plan.md

ln -sf ../../by-type/plans/IDEA-057-text-file-preview.plan.md \
   docs/artefacts/by-topic/frontend/IDEA-057-text-file-preview.plan.md

# Example: Antigravity analysis
cp ~/.gemini/antigravity/brain/<conversation-id>/artifacts/devlog_analysis.md \
   docs/artefacts/by-type/analyses/devlog_analysis.md

ln -sf ../../by-type/analyses/devlog_analysis.md \
   docs/artefacts/by-topic/security/devlog_analysis.md

5. Unsaved-artefacts audit (run periodically)

#!/bin/bash
# Find IDE-generated artefacts not yet imported into the project tree.
# Adjust PROJECT_KEYWORDS to match IDEA numbers, feature names, modules from AGENTS.md/CLAUDE.md.
PROJECT_KEYWORDS="${1:-myproject|IDEA-|ai_service|dashboard}"

echo "=== 🔍 IDE artefacts potentially related to this project ==="

check_source() {
    local label="$1"
    local pattern="$2"
    for f in $pattern; do
        [ -f "$f" ] || continue
        if grep -qiE "$PROJECT_KEYWORDS" "$f"; then
            basename=$(basename "$f")
            # Heuristic: is a file with a similar name already under docs/artefacts/?
            if ! find docs/artefacts/ -name "*${basename%.*}*" 2>/dev/null | grep -q .; then
                echo "  [$label] NOT SAVED: $basename"
            fi
        fi
    done
}

check_source "Cursor"      "$HOME/.cursor/plans/*.plan.md"
check_source "Antigravity" "$HOME/.gemini/antigravity/brain/*/artifacts/*.md"

6. Retrieve from the project tree (for downstream work)

Once imported, artefacts are discoverable via simple path queries:

# By agent
find docs/artefacts/by-agent/researcher/ -name "*.md"

# By type
find docs/artefacts/by-type/validations/ -name "*DJANGO*"

# By topic
find docs/artefacts/by-topic/django-architecture/ -name "*.md"

# Full-text
grep -rli "multi-tenant" docs/artefacts/

Taxonomy Reference

docs/artefacts/
├── by-agent/              # who generated it
│   ├── researcher/
│   ├── test-engineer/
│   └── architect/
├── by-type/               # what kind of artefact
│   ├── plans/             # completed IDE plans (Cursor Plan Mode etc.)
│   ├── analyses/          # exploratory analysis / walkthroughs
│   ├── validations/       # test / validation reports
│   ├── research/          # background research notes
│   └── reports/           # status / audit reports
└── by-topic/              # cross-cutting concern (symlinks into by-type/)
    ├── architecture/
    ├── deployment/
    ├── security/
    ├── frontend/
    └── backend/

by-type/ is the canonical store. by-topic/ holds symlinks for discovery. by-agent/ is optional; skip it if your project doesn't track per-agent provenance.

Example Use Cases

🎯 Project onboarding

New agent session starts, checks docs/artefacts/by-topic/architecture/ for validated patterns before proposing new designs.

🔄 Cross-IDE continuity

Cursor plan for IDEA-057 was generated yesterday; today a Claude Code session picks it up from docs/artefacts/by-type/plans/ and implements against it.

🧪 Production readiness

Before deployment, sweep docs/artefacts/by-type/validations/ for prior sign-offs on related components.

🧹 Periodic cleanup

Weekly run of the unsaved-artefacts audit (§5) captures anything new from Cursor / Antigravity workspaces.

Why This Is Generic

• Assistant-agnostic: Cursor, Claude Code, Antigravity, and future assistants all drop generated work into predictable host locations.
• Project-agnostic: any project can adopt the docs/artefacts/ taxonomy with a single mkdir -p.
• Format-agnostic: Markdown with YAML frontmatter is universally readable; symlinks are universally resolvable.
• Knowledge preservation: artefacts outlive individual agent sessions and IDE workspaces.
• No lock-in: plain files in the repo, no special tooling required to read them.

References

• Agent Artefacts Knowledge Base
• Multi-dimensional Taxonomy
• Git Workflow Rule