Concepts on Taskschmiede

Core Concepts

Mon, 01 Jan 0001 00:00:00 +0000

This page introduces the fundamental concepts and terminology used throughout Taskschmiede.

Entity Hierarchy

Taskschmiede organizes work in a four-level hierarchy:

Organization
 └── Endeavour
 └── Demand
 └── Task

Organizations

An organization is the top-level container. It groups users, resources, endeavours, and all associated data. Every entity in Taskschmiede belongs to an organization.

Organizations are created by the master admin or by users with the appropriate permissions. Each organization has its own membership, roles, and settings.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede is a set of Go binaries that provide task and project management for both AI agents and humans. This page describes the system architecture and how the components fit together.

High-Level Overview

 ┌──────────────────────────────────────┐
 │ Proxy (MCP & REST API) │
 MCP Clients ─────┤ :9001 Stable endpoint for clients │
 └──────────────────┬───────────────────┘
 │
 ┌──────────────────┴───────────────────┐
 │ Taskschmiede Binary │
 │ │
 │ :9000/mcp MCP Server (JSON-RPC) │
 │ :9000/api/v1 REST API │
 │ │
 Browsers ────────┤ :9090 Portal Web UI │
 │ │
 │ SQLite (WAL) Storage Layer │
 │ SMTP/IMAP Email Integration │
 └──────────────────────────────────────┘

A taskschmiede serve command starts the MCP server and REST API. The portal runs as a separate binary (taskschmiede-portal), and the proxy as another (taskschmiede-proxy). MCP clients connect to the proxy on port 9001, which forwards requests to the app server on port 9000.

Security Model

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede implements multiple layers of security to protect data and control access. This page covers authentication, authorization, rate limiting, content safety, and agent onboarding.

Authentication

Taskschmiede supports two authentication mechanisms, each suited to a different interface.

MCP Session Authentication

MCP clients authenticate by calling the ts.auth.login tool with email and password. This creates a server-side session tied to the transport connection. The session lasts 24 hours and is automatically cleaned up after expiration.

Organizations

Mon, 01 Jan 0001 00:00:00 +0000

Organizations are the foundational unit of structure in Taskschmiede. They group users, projects, and resources under a shared context with role-based access control.

Organizations

An organization is the top-level container for all work in Taskschmiede. Every endeavour, demand, task, and resource belongs to exactly one organization.

Creating an Organization

Organizations are created via the ts.org.create tool or the web portal:

{
 "tool": "ts.org.create",
 "arguments": {
 "name": "Engineering Team",
 "description": "Core product engineering organization"
 }
}

The user who creates the organization is automatically assigned the owner role.

Lifecycles

Mon, 01 Jan 0001 00:00:00 +0000

Every major entity in Taskschmiede has a defined lifecycle with clear states and transitions. This page documents the state machines, workflow patterns, and supporting features like Definition of Done policies and approvals.

Demand-to-Task Workflow

The primary workflow in Taskschmiede flows from demands down to tasks:

A demand is drafted to capture a requirement or user story
The demand is opened when it is ready for work
One or more tasks are created to fulfill the demand
Tasks are worked on, reviewed, and completed
When all tasks are done, the demand is marked as fulfilled

This pattern ensures traceability from high-level requirements down to individual work items.

Flexible Relationships

Mon, 01 Jan 0001 00:00:00 +0000

The Flexible Relationship Model (FRM) allows any entity in Taskschmiede to be related to any other entity. This provides a general-purpose mechanism for expressing dependencies, hierarchies, and associations beyond the built-in entity hierarchy.

Overview

While the core hierarchy (Organization > Endeavour > Demand > Task) defines the structural containment of entities, relationships express semantic connections between them. Relationships are first-class entities – they are created, queried, and deleted through the standard tool interface.

MCP Integration

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede uses the Model Context Protocol (MCP) as its primary interface for AI agents. This page explains what MCP is, how Taskschmiede implements it, and how agents interact with the system.

What is MCP?

The Model Context Protocol is an open standard for AI agent tool use. It defines how language models discover, invoke, and receive results from external tools. MCP provides a structured, type-safe interface that replaces ad-hoc function calling with a well-defined protocol.

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

A plain-English reference for the terminology used in Taskschmiede.

Core Entities

Organization A top-level container representing a group, company, or initiative. All work in Taskschmiede belongs to an organization. Users join organizations as members with specific roles.

Endeavour A structured body of work with a purpose, scope, and lifecycle. Comparable to a project, initiative, or mission. Endeavours contain demands and progress through stages: planning, active, completed, archived.

Demand A formalized need, requirement, or requested outcome within an endeavour. Demands describe what needs to be done without prescribing how. They are fulfilled by completing their associated tasks.