Standard operating procedures for project management

GitHub stars
10

Install

/plugin install workflows@typedown

Run it inside Claude Code after adding the marketplace with /plugin marketplace add IndenScale/Typedown.

Contents

Discovered from source

Skills 3

Git Reference Manager

This skill provides guidance on how to formally introduce external repositories into a project for reading and learning. This is crucial for understanding third-party library architectures or finding best practices.

Core Rules

Isolation Principle: Reference code must be strictly isolated within the _reference/ directory. It is strictly forbidden to commit it to the main project's Git history.

Standard Workflow

When you need to reference an external repository (e.g., anthropics/skills or pandas), you must strictly follow these three steps in order:

1. Prepare Sandbox

First, ensure the dedicated directory for storing reference materials exists.

  • Check: Does the _reference directory exist in the project root?

  • Action: If not, create it.

    mkdir -p _reference
    

2. Secure Boundary

Before pulling any code, you must ensure that Git ignores this directory.

  • Check: Does the .gitignore file contain _reference/?

  • Action: If not, append it to the end of the file.

    # Check
    grep "_reference/" .gitignore
    # Append (if missing)
    echo -e "\n# External References\n_reference/" >> .gitignore
    

3. Fetch References

Clone the target repository into a subdirectory within the sandbox.

  • Naming: Use the repository name as the subdirectory name.

  • Action: Use git clone.

    git clone <REPO_URL> _reference/<REPO_NAME>
    
  • Note: Deep history is not required; it is recommended to use --depth 1 to save time and space.

    git clone --depth 1 https://github.com/anthropics/skills.git _reference/anthropics_skills
    

Best Practices

  • Read-Only Mode: Treat all files under _reference/ as read-only. Do not modify them unless it is for testing certain changes (but be aware that changes will be lost).
  • Search via grep: Use grep or ripgrep to search for code patterns within the reference directory.
  • Discard Anytime: Since these files are ignored by git and can be re-cloned, you can delete them at any time to free up space after finishing your task.

Example

User Request: "I want to see how React's source code handles Hooks."

Agent Execution:

  1. mkdir -p _reference
  2. grep "_reference" .gitignore || echo "_reference/" >> .gitignore
  3. git clone --depth 1 https://github.com/facebook/react.git _reference/react
  4. Start reading _reference/react/packages/react-reconciler/...

Task Expert

This skill provides guidance on following the Task as Code philosophy. In this system, conversations are fluid, but tasks are persistent. All non-trivial changes must be documented in task files.

Core Workflow

1. Task Identification and Creation

When a specific requirement or bug is identified, a new task should be immediately created in the todos/zh/active/ directory.

  • ID Allocation: Find the current maximum TASK-XXXX number and increment it by 1.
  • File Naming: TASK-{ID}-{slug}.md (lowercase, hyphen-separated).
  • Front matter: Must include id, type, status, title, created_at, author.

2. Develop and Document

During task execution, the task file is the "Source of Truth":

  • Context: Record background information in the file.
  • Objectives: Define clear deliverables.
  • Plan: Maintain a task list (Checkboxes) in the file.
  • Thought: Record key design decisions or technical pivots.

3. Task Archiving

When a task status changes to done or cancelled:

  • Update the status in the Front matter.
  • Move the file from active/ to archive/.

File Format Standards

Task files must use the following structure:

---
id: TASK-XXXX
type: task
status: active # active | done | cancelled
title: 'Task Title'
created_at: 202X-XX-XX
author: [Your Name]
---

# TASK-XXXX: [Task Title]

## Background

[Briefly explain why this task is needed]

## Objectives

- [ ] Objective 1
- [ ] Objective 2

## Workflow/Notes

[Record thoughts, command outputs, or key code snippets during execution]

Antipatterns

  • Skipping IDs: Strictly forbidden to skip ID numbers.
  • Forgetting: Strictly forbidden to close a conversation without updating statuses.
  • Clutter: Strictly forbidden to pile up completed tasks in the active/ directory.
  • Hidden Logic: Strictly forbidden to discuss complex logic only in the conversation without persisting it in task files.

Examples

  • todos/zh/active/TASK-0005-setup_skills_reference.md
  • todos/zh/archive/TASK-0004-fix_pydantic_validation.md

Typedown Expert

This skill provides expert knowledge for writing Typedown files (.td). Typedown is a Consensus Modeling Language that embeds Pydantic models and Pytest logic into Markdown.

Core Syntax Rules

  1. File Structure:

    • Typedown files are valid Markdown files.
    • They consist of natural language text interleaved with special Code Blocks.
    • Crucial: Every .td file MUST start with a Level 1 Heading (# Title) and a brief textual description. Never start with a code block.
  2. Model Blocks (model:<Name>):

    • Used to define Pydantic models.
    • One Model Per Block: Do NOT define multiple classes in a single block. Each class gets its own model:ClassName block.
    • No Imports in Block: Do NOT import typing or pydantic inside the block unless it's a specific, non-standard import. The environment pre-loads standard types.
    • Class Name Match: The class defined MUST match the block argument (e.g., class User inside ```model:User).
  3. Config Blocks (config):

    • Used for global configuration and exports.
    • Location: Strictly restricted to config.td files only. Do NOT use config blocks in regular .td files.
    • Exposure: All symbols defined in config are automatically exposed to the directory scope and inherited by subdirectories.
  4. Entity Blocks & Identifiers:

  • Every Entity MUST have a unique identity.
  • Syntax: entity <Type>: <ID>
  • The ID:
    • The string after the colon is the entity identifier.
    • Styles: Can be a simple name (alice) or a slug (user-alice-v1).
  • Content: Valid YAML matching the Pydantic model.
    • Reference Rule: When referencing other entities within an entity block, you MUST use the [[ID]] (Wiki Link) syntax.
  1. References ([[...]]):
  • Typedown supports two reference forms:
    1. ID Reference: [[id]]
      • Lookup by name in the current scope or global index.
      • Examples: [[alice]], [[users/alice]]
    2. Hash Reference: [[sha256:...]]
      • Match content hash exactly for immutable references.
      • Used for version locking and history tracking.
  1. Evolution Semantics (former):

When tracking object changes over time:

  • Syntax: former: [[<Identifier>]]
  • Rule: You MUST use the reference syntax [[]] for the former field.
  • Rule: Prefer using Content Hash for former pointers to ensure historical stability. Globally unique IDs are also acceptable.
  1. Spec Blocks (spec):
  • Used for validation logic.
  • Contains Python functions decorating with @target.

The Typedown Mindset: Consensus Modeling

Typedown is not just a syntax; it is a rigorous method for converting loose natural language into strict systemic consensus. When using Typedown, follow this 5-step cognitive process:

1. Entity Discovery (Identification)

Scan the unstructured text or requirement to identify Key Entities. Immediately instantiate them using entity blocks to fix their existence.

  • Action: Create entity:<Type> blocks with YAML content.
  • Goal: Turn "User Alice" into data.

2. Schema Abstraction (Structure)

Analyze the entity blocks you just created. Abstract their common structure into Pydantic models (model).

  • Action: Define model:<Type> blocks.
  • Context: Place shared models in a parent config.td or common.td and export them if they are used across multiple files.

3. Constraint Engineering (Logic)

Analyze the business rules governing these entities. Enforce them using three layers of defense:

  • Layer 1 (Field Types): Use strict types (e.g., EmailStr, PositiveInt).
  • Layer 2 (Validators): Use Pydantic @field_validator or @model_validator for self-contained consistency.
  • Layer 3 (Specs): Use spec blocks with @target tags for cross-entity or graph-level validation (e.g., "A specific user must exist in the admin group").

4. Reference & Learning (Research)

If you are unsure about advanced syntax (e.g., how to use former for versioning or tags for filtering):

  • Action: Create a _reference directory (it is git-ignored).
  • Action: Clone the official repo: git clone https://github.com/IndenScale/typedown.git _reference/typedown.
  • Action: Read docs/ or cookbook/01_getting_started/ in the reference to ground your knowledge.

5. Verification (Feedback)

Never assume your code is correct. Always verify with the compiler.

  • Action: Run uvx typedown check <path> immediately after editing.
  • Action: Treat warnings as errors.

Example: The Modeling Loop

  • Step 1: Raw Draft "We need a server 'Alpha' compliant with ISO-27001."

  • Step 2: Typedown Modeling

class ComplianceStandard(str, Enum):
    ISO_27001 = "ISO-27001"
    SOC2 = "SOC2"
class Server(BaseModel):
    hostname: str
    compliance: List[ComplianceStandard]

    @model_validator(mode='after')
    def check_security(self):
        if ComplianceStandard.ISO_27001 in self.compliance:
            # Enforce some logic...
            pass
        return self
hostname: "alpha-01"
compliance:
  - "ISO-27001"

Sponsors

Details

Marketplace
IndenScale/Typedown
Source
https://github.com/IndenScale/Typedown.git
Category
Community

More from IndenScale/Typedown

All 2