PUMA Vault

PUMA Vault — Complete User Guide

Se lee en 19 min

PUMA Logo

📘 PUMA Vault — Complete User Guide

PUMA — PUMA Understanding and Management with Agents

[!info] Overview

Can language models manage ICT projects? An empirical benchmark of local LLM agents for issue triage and effort estimation in ICT projects.

Version 1.0 · Updated April 2026

Quick Navigation

DestinationDescription
index.mdPublished landing page
README.mdGitHub repository landing page
00 - Home.mdNavigation hub

Vault Sections

SectionDescription
00 - MetaTemplates, dashboards, plugin configuration
10 - InboxGTD capture point — fleeting notes and quick capture
20 - LiteraturePapers, books, videos, tools, datasets
30 - PermanentZettelkasten — concepts, methods, frameworks, results
40 - ProjectsActive project work — chapters, specs, experiments, BMAD
50 - AreasOngoing responsibilities — research, writing, code, ethics
60 - ResourcesPrompts, workflows, checklists, glossary, bibliography
70 - ArchiveCompleted and deprecated material
80 - MOCMaps of Content — navigation and synthesis layer
90 - GTDTasks, reviews, sprint boards, someday/maybe

What is this vault?

This is the PUMA Knowledge Vault — a professional workspace for the PUMA Project. It integrates four knowledge management systems (PARA, GTD, Zettelkasten, Johnny Decimal) with academic research workflows (SLR, DSR, Keshav Three-Pass) and development methodologies (SDD, BMAD, OpenSpec, CDD).

Single principle: every piece of information has a clear home, a clear purpose, and a clear path to the PUMA Project.

5-Minute Setup

  1. Open Obsidian → Open Vault → select this folder
  2. Trust author (for Templater to work)
  3. Install plugins: Settings → Community Plugins → Browse → install each plugin in Recommended-Plugins
  4. Set Homepage plugin: open 00 - Home.md as startup page
  5. Configure Zotero Connector: point to your Zotero library
  6. Run git init in vault root if using Git backup

Daily Workflow (GTD)

Morning (10 min):

  1. Open 90 - GTD/95 Reviews/Daily-Review-Template → create today’s note with Templater
  2. Check 90 - GTD/91 Tasks/TASKS-Active for overdue and due-today tasks
  3. Check 10 - Inbox/ for unprocessed fleeting notes

During work:

  • New ideas/sources → 10 - Inbox/Fleeting-Notes/ (use Template-Fleeting-Note)
  • New papers → use Zotero connector → routed to 20 - Literature/20.1 Papers/
  • New tasks → inline - [ ] Task 📅 YYYY-MM-DD in relevant project note

Evening (5 min):

  • Process inbox items that accumulated
  • Update task statuses

Weekly Workflow (GTD Weekly Review)

Every Sunday or Monday, open 90 - GTD/95 Reviews/Weekly-Review-Template:

  1. Process Inbox to zero
  2. Review all active projects (PEC progress, sprint board)
  3. Convert Fleeting Notes → Literature Notes or Permanent Notes
  4. Update MOCs with new connections
  5. Review Waiting For items (advisor feedback, etc.)
  6. Plan next week’s tasks

How to Add a New Paper

Option A — with Zotero (recommended):

  1. Import paper to Zotero → tag #puma-include
  2. Use Obsidian Zotero Integration plugin: Ctrl+Shift+Z → search → insert
  3. Paper lands in 20 - Literature/20.1 Papers/ as @citekey.md
  4. Fill Keshav Three-Pass template

Option B — manual:

  1. Copy 00 - Meta/Templates/Template-Keshav-ThreePass.md
  2. Place in appropriate 20 - Literature/20.1 Papers/[Topic]/ subfolder
  3. Fill all fields; set status: to-read

How to Add a Permanent Note (Zettelkasten)

  1. Complete Keshav Pass-3 on a paper (or have a new insight)
  2. Copy 00 - Meta/Templates/Template-Permanent-Note.md
  3. Title must be a declarative statement (e.g., “RAG retrieval improves precision when historical examples are structurally similar to the query”)
  4. Place in 30 - Permanent/31 Concepts/, 32 Methods/, or 33 Frameworks/ based on content
  5. Link to: source literature note, related permanent notes, relevant MOC
  6. Never move a permanent note — only add links

How to Run an Experiment

  1. Check spec in 40 - Projects/PUMA/41.6 Specs/ — validate against constitution
  2. Add experiment to 40 - Projects/PUMA/41.7 Experiments/ using Template-Experiment-Note
  3. Create task in 90 - GTD/96 Kanban/Sprint-02-Board.md
  4. Run code (CodeCarbon wrapping all inference)
  5. Log results in 40 - Projects/PUMA/41.4 Results/
  6. Update 00 - Meta/Dashboards/Dashboard-Experiment-Status

Methodology Quick Reference

When you…Use this methodNotes live in
Capture a quick ideaGTD Capture → Fleeting Note10 - Inbox/
Read a new paperKeshav Three-Pass20 - Literature/
Synthesise an insightZettelkasten Permanent Note30 - Permanent/
Work on PUMA chapterPARA Project40 - Projects/PUMA/
Use AI assistanceRCOIF + CDD60 - Resources/61 Prompts/
Plan a sprintGTD + Agile90 - GTD/96 Kanban/
Simulate agent teamBMAD40 - Projects/41.9 BMAD-Agents/
Write a specSDD + Spec Kit40 - Projects/41.6 Specs/
Find any fileJohnny Decimal60 - Resources/66 JD-Index/
Navigate topicsMOC80 - MOC/

Plugin Quick Reference

PluginShortcutUse
DataviewautoDynamic tables and queries
TemplaterAlt+TInsert template into current note
Tasksinline - [ ]Task tracking everywhere
Kanbanopen .mdSprint board
QuickAddCtrl+Shift+AFast note creation
Zotero IntegrationCtrl+Shift+ZImport papers
Obsidian GitCtrl+Shift+GBackup to GitHub
CalendarsidebarNavigate to any date

File Naming Conventions

TypePrefixExample
Literature NoteLN-LN-Angermeir-2025-Reproducibility.md
OR Zotero citekey@@Angermeir2025Reproducibility.md
Permanent NotePN-PN-RAG-Embeddings-VectorDB.md
Project NotePR-PUMA-PR-PUMA-Ch1-Introduction.md
SpecSP-SP-Architecture-v1.md
ExperimentEX-EX-Hypotheses-H1-H2.md
Prompt TemplatePT-PT-PUMA-Experiment-Prompts.md
WorkflowWF-WF-SLR-Pipeline.md
ChecklistCL-CL-Quality-Checklists.md
MOCMOC-MOC-PUMA-Master.md

Vault Architecture (Johnny Decimal)

00 — Meta (templates, plugins, CSS)
10 — Inbox (GTD capture point)
20 — Literature (papers, books, datasets, tools)
30 — Permanent (Zettelkasten: concepts, methods, frameworks)
40 — Projects (PUMA: chapters, specs, experiments, BMAD)
50 — Areas (research quality, writing, code, sustainability)
60 — Resources (prompts, workflows, checklists, glossary, bibliography, JD-index)
70 — Archive (completed, deprecated)
80 — MOC (Maps of Content — navigation layer)
90 — GTD (tasks, reviews, kanban, someday/maybe)

Knowledge Management Methodologies

The vault fuses six complementary knowledge management systems into a single coherent workspace. Each system is not used in isolation — they reinforce each other, each covering a different dimension of the research lifecycle.

Research Pipeline

MOC — Maps of Content

MOC notes act as index pages that gather links to related notes by topic, forming a navigable graph of knowledge rather than a rigid hierarchy. Each major domain (agents, benchmarks, methods, tools, videos) has a dedicated MOC in 80 - MOC/81 Topic-Maps/. The MOC layer is the primary navigation surface for the vault; it replaces folders as the main organizational paradigm at the semantic level.

GTD — Getting Things Done

David Allen’s GTD system governs all task and commitment management. The vault’s 90 - GTD/ area houses the active task list, master projects list, and someday/maybe queue. Daily and weekly reviews (templated) ensure that captured tasks are processed, clarified, and either acted upon, deferred, or discarded. GTD prevents the research inbox from becoming a graveyard of unprocessed ideas.

PARA — Projects · Areas · Resources · Archive

Tiago Forte’s PARA framework provides the macro-level organizational skeleton. 40 - Projects holds active, deadline-bound research work. 50 - Areas contains ongoing responsibilities with no end date. 60 - Resources stores reusable assets. 70 - Archive holds completed material. PARA ensures every note has a home and that homes decay gracefully as work evolves.

Zettelkasten

Niklas Luhmann’s slip-box methodology generates atomic, permanent, densely-linked knowledge notes in 30 - Permanent/. Each permanent note encodes a single idea, carries a unique identifier, and links to related notes by concept rather than by topic. The Zettelkasten is the intellectual core of the vault. Literature notes (LN-) feed the Zettelkasten; permanent notes (PN-) are its output.

Johnny Decimal

A numeric address system that assigns a unique two-digit code to every area (00–90) and a decimal sub-code to every sub-area (20.1, 20.2, …). This prevents folder sprawl, enables precise cross-referencing (e.g., see 60.64 Glossary), and makes every file findable by its address alone.

SDD / BDD / BMAD

Spec-Driven Development (SDD) treats formal specifications as the source of truth. Behaviour-Driven Development (BDD) expresses requirements as human-readable scenarios. BMAD (Build, Manage, Adapt, Deploy) is an AI-native project management methodology that orchestrates specialized AI agents through clearly defined roles (Analyst, Architect, QA, etc.) using structured PRDs and sprint boards.

Research Frameworks

PUMA integrates a layered stack of research methodologies — from the macro study design down to the micro level of individual prompting strategies.

Primary Research Methods

  • EBSE + SLR / PRISMA: Evidence-Based Software Engineering and Systematic Literature Review (reported using PRISMA 2020) map the state of the art on LLM agents.
  • DSR — Design Science Research: Hevner et al.’s framework treats the PUMA agent platform as an artifact to be evaluated against utility criteria.
  • Grounded Theory: Used for qualitative analysis of emergent patterns — particularly for analysing agent reasoning traces and failure modes.
  • MIT Student Method: A structured research workflow (vision → steps → news) from the MIT AI Lab (Working Paper WP316). Literature notes follow a three-pass reading protocol (Keshav 2007).

Prompting & Agent Engineering Frameworks

FrameworkCategoryDescription
RCOIFPromptingRole · Context · Objective · Instructions · Format. Default format across the vault.
EGIPromptingExplicit Goal-setting and Iterative refinement loop.
AMIPromptingAnchored Multi-step Inference to prevent reasoning drift.
DRCAPromptingDecompose · Reason · Critique · Answer.
IIPRPromptingIntent · Information · Process · Result.
CoTPromptingChain-of-Thought prompting for step-by-step reasoning.
Few-ShotPromptingProvides 3–8 labelled examples in the prompt context.
Zero-Shot CoTPromptingModel reasons without examples, guided by “think step by step”.
CDDDevelopmentContext-Driven Development: treatments of context window as primary design space.
Agent OSArchitectureFramework for orchestrating specialized agents through a shared interface.
Agent Prompt EngineeringArchitectureDiscipline of designing and testing system prompts for autonomous agents.

Note Types & Prefixes

Every note carries a prefix encoding its type, enabling Dataview queries, filtered searches, and Zettelkasten linking. The lifecycle flows: raw capture → literature note → permanent note → project reference → MOC entry.

PrefixTypeLocationExample
FL-Fleeting Note10 - InboxFL-2026-03-15-LLM-idea
LN-Literature Note20 - LiteratureLN-Tawosi2022-TAWOS
PN-Permanent Note30 - PermanentPN-Few-Shot-Prompting
ST-Structure Note30 - PermanentST-Prompting-Strategies
SRC-Source Note30 - Permanent/36 SourcesSRC-Keshav-2007-HowToReadPaper
PER-Person Note30 - Permanent/37 PersonsPER-Yao-Shunyu
RES-Results Note30 - Permanent/34 ResultsRES-Results-Placeholders
PR-Project Note40 - ProjectsPR-PUMA-Ch1-Introduction
SP-Spec Note40 - Projects/SpecsSP-Triage-Agent-v1
EX-Experiment Note40 - Projects/ExperimentsEX-Llama32-ZeroShot-Triage
PT-Prompt Template60 - Resources/61 PromptsPT-Claude-RCOIF-Research
WF-Workflow Note60 - Resources/62 WorkflowsWF-SLR-Pipeline
CL-Checklist60 - Resources/63 ChecklistsCL-Quality-Checklists
BIB-Bibliography60 - Resources/65 BibliographiesBIB-Master-APA7
KW-Keyword Map60 - Resources/64 GlossaryKW-Category1-AI-Agents
VID-Video Note20 - Literature/20.4 Videos-PodcastsVID-AGT-001-Karpathy-RAG
GT-GTD Note90 - GTDGT-Weekly-Review-2026-W10
MC-Map of Content80 - MOCMC-LLM-Benchmarks
BMAD-BMAD Agent Doc40 - Projects/BMAD-AgentsBMAD-PRD-PUMA

The .claude Folder & Skills

The .claude/ folder is the AI integration layer of the vault. It contains the PUMA skill library (custom skills) and the obsidian-skills plugin. These turn Claude Code into a domain-aware research assistant that understands vault conventions and research methodologies.

PUMA Custom Skills

+ Click to expand
  • puma-core: Defines project identity, Johnny Decimal rule set, and thinking framework.
  • puma-orchestrator: Protocols for coordinating specialized agents.
  • puma-agent-design: Guidelines for agent roles, tool specs, and memory architecture.
  • puma-agile: Agile conventions adapted for AI-assisted development cycles.
  • puma-bmad: BMAD method implementation: PRD formats and agent rosters.
  • puma-cdd: Context-Driven Development rules and context window budgeting.
  • puma-experiment: Protocol for reproducible experiment notes and logging.
  • puma-openspec: Standards for writing machine-readable specifications.
  • puma-sdd: Spec-Driven Development conventions (spec-first workflow).
  • puma-spec-kit: Templates for architecture, agents, and datasets.
  • puma-moc: Rules for creating and maintaining Maps of Content.
  • puma-zettelkasten: Atomic note principles and Zettelkasten Hub rules.
  • puma-rcoif: Implements the RCOIF prompting framework.
  • puma-cot: Chain-of-Thought prompting guidelines.
  • puma-prompting: Master skill consolidating all prompting frameworks.
  • puma-advanced-prompt: Self-consistency, multi-turn design, and red-teaming.
  • puma-research: Master research skill for the PUMA pipeline.
  • puma-literature-review: SLR execution protocol (PICO/PRISMA).
  • puma-keshav-method: Three-pass paper reading protocol implementation.
  • puma-mit-student-method: vision → steps → news structure.
  • puma-dataview: Dataview query syntax for dynamic indexing.
  • puma-research-tools: Reference for Semantic Scholar, ResearchRabbit, etc.
  • puma-zotero: Integration conventions for citations.
  • puma-vault-architecture: Johnny Decimal address ranges and folder semantics.
  • puma-obsidian-governance: Plugin configuration and frontmatter schema.
  • puma-rules: Binding governance rules (Always/Never).
  • puma-anti-patterns: Catalogue of mistakes to avoid (e.g., flat file dumps).
  • puma-obsidian-cli: Instructions for interacting with the vault from the terminal.

Obsidian-Skills Plugin

+ Click to expand
  • obsidian-markdown: Reference for callouts, embeds, and frontmatter.
  • obsidian-cli: Reference for obsidian create, search, and open commands.
  • obsidian-bases: Reference for the native database feature.
  • json-canvas: JSON Canvas format specification for programmatic editing.
  • defuddle: Skill for extracting clean text from web pages.

Tools, Platforms & Research Ecosystem

Purpose

This section systematically documents and provides traceability for the entire ecosystem of tools, digital platforms, and public profiles utilized in the development of the PUMA Project. Transparency in the use of research and development tools is a primary ethical and methodological requirement, especially when employing Generative AI systems as epistemic partners in the research process.

Primary Access Points & Repositories

Code & Documentation Hubs

All technical artifacts, specifications, and the research vault are hosted on GitHub under the pumacp organization.

ResourceDescriptionURL
GitHub OrganizationMain project hubhttps://github.com/pumacp
PUMA Vault (Source)Obsidian Vault source fileshttps://github.com/pumacp/puma-vault
PUMA Vault (Web)Live web version of the Vaulthttps://pumacp.github.io/puma-vault/
GitHub Vault WikiProject documentation wikihttps://github.com/pumacp/puma-vault/wiki
PUMA Code RepoMain application source codehttps://github.com/pumacp/puma
YouTube PlaylistDemonstrations & Video logshttps://www.youtube.com/feed/playlists

AI-Powered Research Platforms

NotebookLM Research Notebooks

The following notebooks represent specialized AI contexts trained on the project’s specific bibliographic corpus for synthesis and deep analysis.

Consensus Academic Search Profiles

Publicly shared searches and bibliographies focused on evidence-based AI research.

Knowledge & Bibliographic Management

Zotero Public Library

Centralized metadata and PDF management for all project citations.

PUMA Public Library (Zotero)

RSS/API Access: JSON/Atom Feed

Researcher.Discovery Reading Lists

Curated collections for specific project domains.

Collection NameLink
Main PUMA LibraryAccess List
LLM Benchmark CoreAccess List
Project Management BenchmarksAccess List
Local LLM BenchmarkingAccess List
LLM Based AgentsAccess List
Phase 1: Scientific IdeationAccess List
Phase 2: Literature DiscoveryAccess List
Phase 3: Systematic ReviewAccess List
Phase 4: Theoretical FrameworkAccess List
Phase 5: Hypothesis GenerationAccess List
Phase 6: Experimental DesignAccess List
Phase 7: Critical AnalysisAccess List
Phase 8: Scientific WritingAccess List
Phase 9: Review OutputAccess List

ResearchRabbit & Storage

Generative AI Research Partners

Custom AI Profiles & Spaces

Research Session Artifacts

Ecosystem Table

CategoryPrimary ToolsMethodology / Key Standard
D.1 RepositoriesGitHub, Pages, WikiSDD, Open Source, DSR
D.2 AI ResearchNotebookLM, Consensus, R.DiscoverySLR, PRISMA, Keshav
D.3 AI AssistantsClaude, ChatGPT, GeminiPrompt Engineering, Chain-of-Thought
D.4 DocumentationObsidian, GitHub PagesZettelkasten, PARA, Johnny Decimal

Full Index of Files

All files are listed as clickable relative links, organized by folder following the Johnny Decimal structure.

Root

00 — Meta 25 files

Dashboards

Plugins-Config

Snippets

Templates

+ Click to expand

10 — Inbox 4 files

Fleeting-Notes

Quick-Capture

20 — Literature ~160 files

20.1 Papers

+ Click to expand
Agent-Architectures
+ Click to expand
Agentic-Science
AI-Knowledge-Generation
+ Click to expand
AIOps-DevOps
Effort-Estimation
LLM-Agents-General
+ Click to expand
PM-AI-Convergence
Reproducibility-SE
Research-Methods
Scheduling-MAS
Triage-Benchmarks

20.2 Books

20.3 Datasets

20.4 Videos-Podcasts

+ Click to expand
YouTube / Context-Engineering
+ Click to expand
YouTube / Dev-Tools-IDE
+ Click to expand
YouTube / LLM-Agents-MultiAgent
+ Click to expand
YouTube / Local-LLM-Ollama
+ Click to expand
YouTube / MCP-Protocols
+ Click to expand
YouTube / Miscellaneous
+ Click to expand
YouTube / Observability-Testing
+ Click to expand
YouTube / PM-Agile-AI
+ Click to expand
YouTube / RAG-VectorDB
+ Click to expand
YouTube / Research-Literature
+ Click to expand
YouTube / SDD-Specs-BMAD
+ Click to expand

20.5 Repos-Code

+ Click to expand

20.6 Tools

+ Click to expand

20.7 Blog-Web

20.8 Conferences

30 — Permanent (Zettelkasten) 35 files

30 Zettelkasten-Hub

31 Concepts

+ Click to expand

32 Methods

+ Click to expand

33 Frameworks

+ Click to expand

34 Results

36 Sources

37 Persons

+ Click to expand

40 — Projects 19 files

41.1 Introduction

41.2 Literature-Review

41.3 Methods

41.4 Results

+ Click to expand

41.5 Discussion

41.6 Specs

+ Click to expand

41.7 Experiments

+ Click to expand

41.8 Sprint-Boards

41.9 BMAD-Agents

50 — Areas 10 files

51 Research

+ Click to expand

52 Writing

53 Code-Dev

54 Sustainability

55 Ethics

56 Smart-PMO

60 — Resources ~60 files

61 Prompts — General

61.1 LLM-Tools
61.2 Research-Tools
61.3 Dev-Tools
61.5 BMAD-Prompts
Methodologies
+ Click to expand
Phase 1 — Research / 01 Literature-Exploration
+ Click to expand
Phase 1 — Research / 02 Scientific-Mapping
+ Click to expand
Phase 1 — Research / 03 Structured-Extraction
+ Click to expand
Phase 1 — Research / 04 Conceptual-Synthesis
+ Click to expand
Phase 1 — Research / 05 Hypothesis-Generation
+ Click to expand
Phase 1 — Research / 06 Experimental-Design
+ Click to expand
Phase 1 — Research / 07 Critical-Review
+ Click to expand
Phase 2 — Development
+ Click to expand

62 Workflows

+ Click to expand

63 Checklists

64 Glossary

+ Click to expand

65 Bibliographies

+ Click to expand

66 Johnny-Decimal-Index

70 — Archive 3 files

80 — MOC (Maps of Content) 12 files

81 Topic-Maps

+ Click to expand

82 Index

90 — GTD 3 files

.claude — AI Skills & Governance 45 files

.claude / puma / core

.claude / puma / development

+ Click to expand

.claude / puma / integration

.claude / puma / knowledge

.claude / puma / meta

.claude / puma / prompting

+ Click to expand

.claude / puma / research

+ Click to expand

.claude / puma / tools

+ Click to expand

.claude / puma / vault

+ Click to expand

.claude / obsidian-skills

+ Click to expand

Vault Guide v2.0 · April 2026

Vista Gráfica

Retroenlaces